58
VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE DATA PLATFORM 07 Aug 2018

VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

  • Upload
    others

  • View
    4

  • Download
    0

Embed Size (px)

Citation preview

Page 1: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

VOCABULARY SERVICE (SDP-V)

RELEASE 18

SURVEILLANCE DATA PLATFORM

07 Aug 2018

SDP Vocabulary Service

VERSION HISTORY

SDP-V Release

Drafted By

Revision Date

Description of Change

10 R Dingwell A Gregorowicz

E Hathaway S Irivinti

071917 Initial Version

10 D Pellitieri 092717 Adding a description of the accessibility and compatibility features to bring document in line with 508 requirement Subpart_D_1194_41 ID 2b1

14 D Pellitieri 110817 Updating with phase 1A sprint work

14 D Pellitieri 122017 Updating with groups and end of phase 1A edits

18 K Hay 8718 Updating with phase 2 sprint work through Release 18

Page 2 of 58

SDP Vocabulary Service

TABLE OF CONTENTS

1 INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE 5

2 SDP-V GOAL 5

21 SDP-V Overview 6

22 Types of Content in SDP-V 6

23 System Roles And Capabilities Summary 8

231 Viewer (Public) 8

232 Author (Authenticated User) 8

233 Publisher (Authenticated User With Publisher Role) 9

234 Administrator (Authenticated User With Admin Role) 10

24 Collaborative Authoring Groups 11

25 Key Terms 11

26 Operational Status 12

27 Section 508 Compliance and Accesibility Features 12

3 GETTING STARTED 13

31 Accessing SDP-V 13

32 Registering as a User 13

321 Viewer 13

322 Author 13

323 Publisher 13

324 Administrator 14

33 Logging In 14

34 Selecting a Program and Surveillance System 15

35 Navigation Overview 17

36 Logging Out 18

4 INSTRUCTIONS FOR SDP-V USE 19

41 Searching for Content 19

411 Filtering By Type Of Content 20

412 Filtering To ldquoMy Stuffrdquo 21

413 Filtering By Group 22

42 Advanced Search features 22

421 Filtering By Program Surveillance System Or Both 23

422 Sorting Content 24

423 Most Recent Version Filter 25

424 Content Changed Since Filter 26

43 Viewing Details of Existing Content 28

Page 3 of 58

SDP Vocabulary Service

44 Drafting New Content 30

441 Drafting New Questions 30

442 Drafting New Response Sets 33

443 Drafting New Sections 35

444 Drafting New Surveys 37

45 Importing New Content 39

451 Message Mapping Guide (MMG) 39

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template 41

46 Revising and Editing Content 42

47 Extending Content 44

48 Adding Content to Groups 44

49 Commenting on Existing Content 45

410 Exporting Content 46

4101 Epi Info (Surveys and Sections) 46

4102 REDCap (Surveys and Sections) 46

4103 Spreadsheet (XLSX) (Surveys only) 47

4104 PDF (Surveys and Sections) 47

411 Accessing Content via the SDP-V Application Programming Interface (API) 47

412 Requesting that Content be Published 48

5 PUBLISHER FUNCTIONS 49

51 Find Othersrsquo Draft Content 49

52 Publish Draft Content 49

6 ADMINISTRATOR FUNCTIONS 50

61 Admin List amp Publisher List Tabs 50

62 Program List amp System List Tabs 50

63 Elasticsearch Tab 51

64 Group List Tab 51

7 CONTACT US 52

APPENDIX A ACRONYMS 53

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS 54

Page 4 of 58

1

2

SDP Vocabulary Service

INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE

This document serves as a reference for users of the Surveillance Data Platform (SDP) Vocabulary Service (SDP-V) on how to use the application It also provides background and context on the intent of SDP-V the types of content it contains the types of user roles and the actions users are able to take

SDP-V GOAL

The goal of SDP-V is to facilitate discovery and reuse of existing vocabulary content thereby reducing the number of different ways the Centers for Disease Control and Prevention (CDC) asks for the same type of information across programs and surveillance systems (See 12 Figure 1) This will help to reduce state tribal local and territorial (STLT) partner reporting burden as well as drive towards harmonization in data collection instruments

By making it easy for Authors to see how others have asked for certain types of information before SDP-V enables Authors to spend less time creating new data collection instruments (See 3 Figure 1) In other words by reusing what others have done before SDP-V can enhance consistency in how questions are asked and answered Not only is it easier to answer questions asked the same way this consistency also makes it easier to compare answers and see the big picture This should allow users to spend less time figuring out how to ask the right question and spend more time doing the important work of analyzing the results

Figure 1 illustrates how this goal can be achieved by using SDP-V For better clarity this diagram is available for viewing on the SDP Vocabulary Service webpage

Figure 1 - SDP-V Enables Use of Harmonized Questions and Response Sets

Page 5 of 58

SDP Vocabulary Service

21 SDP-V OVERVIEW

SDP-V provides a repository of Response Sets Questions Sections and SDP-V Surveys These content types are described in further detail in Section 22

Content in SDP-V can be created by Authors in the user interface or can be imported from spreadsheets that conform to the message mapping guide (MMG) or SDP-V generic template formats1 Value sets from the Public Health Information Network Vocabulary Access and Distribution System (PHIN VADS)2 are synchronized in SDP-V and can be searched reused and extended by Authors

These artifacts are accessible to SDP-V users via a graphical user interface (GUI) They are also available to other applications through an application programming interface (API)

22 TYPES OF CONTENT IN SDP-V

SDP-V serves as a repository and authoring tool for four different types of content Response Sets Questions Sections and SDP-V Surveys Figure 2 shows how the different types of content are related for better clarity the diagram can also be viewed on the SDP Vocabulary Service webpage

These content types are defined as follows

bull Response Set ndash A set of response choices that are applicable answers to one ormore questions

bull Question ndash Typically a natural language expression used to solicit a value for adata variable like ldquoWhat is your agerdquo In some cases like for defining vocabularyfor electronic information exchange this may be the data element name used tosolicit a value for the data variable instead of a natural language expression likeldquoSubjectrsquos Sexrdquo

o Response- A value that can be given as an answer to a question Commonresponse types include choice text and date3 Response type is a propertyof a question in SDP-V

bull Section ndash A grouping of questions related to a topic (eg demographic clinicallaboratory epidemiological) and intended to appear together as part of a datacollection instrument A section may also contain one or more sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquo and ldquoDiagnosisrdquo sectionswithin a ldquoClinicalrdquo section

bull SDP-V Survey ndash A SDP-V Survey defines the vocabulary (eg questions andresponse sets) used for a particular data collection or information exchange ASDP-V Survey contains one or more Sections that are combined together andintended for a data collection instrument or information exchange

1 Import of content may require coordination with the SDP-V development team See in-app help documentation for supported formats 2 PHIN VADS provides standard vocabularies particularly value sets associated with H7 message implementation guides to CDC and public

health partners More information about PHIN VADS can be found at httpswwwcdcgovphintoolsphinvadsindexhtml 3 A complete list of response types can be found at httpwwwhl7orgfhirvalueset-item-typehtml

Page 6 of 58

SDP Vocabulary Service

Figure 2 SDP-V Component Diagram

Page 7 of 58

SDP Vocabulary Service

23 SYSTEM ROLES AND CAPABILITIES SUMMARY

SDP-V has four defined user roles which allow access to specific content and capabilities These roles defined below include viewer author publisher and administrator In addition to these roles a user can belong to a collaborative authoring group See Section 24 for more information about groups Please see Appendix B Role Capabilities and Workflows for role capabilities and workflow flowcharts

231 VIEWER (PUBLIC) Anyone may browse published content in the Vocabulary service It is accessible to the public

232 AUTHOR (AUTHENTICATED USER) SDP-V Authors are identified by CDC Programs as users expected to add edit revise or curate program content To become an SDP-V Author users go through a CDC SDP-V onboarding process to obtain the needed credentials The SDP program calls this becoming an ldquoAuthenticated Userrdquo Users interested in becoming an Author should contact the SDP program (see Section 7)

2321 AUTHOR CAPABILITIES A summary of capabilities available to Authors in SDP-V is as follows bull Browse search and view details of all published contentbull Create new content (draft content until published)bull Import content (MMG or SDP-V template format)bull Browse and edit their own draft contentbull Browse and revise their own published contentbull Browse and extend published content Extending content creates a copy of

published content to use as a starting point for a userrsquos own contentExtending content creates a draft copy that includes a link to the content itwas extended from for traceability

bull Export contentbull Request draft content be published

2322 AUTHOR EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for the Author role to maximize the value of SDP-V

bull Authors are expected to reuse existing SDP-V content when possible toreduce variability and evolve toward harmonization Where reuse is notpractical Authors should document a justification to share with Publishers

bull When creating new Questions Sections and Surveys Authors are expectedto use Tags (see Section 44) whenever possible to make it easier for othersto search for and reuse content

bull Authors should verify that the Program and Surveillance System associatedwith their account in SDP-V (see Section 34) is accurate when they are

Page 8 of 58

SDP Vocabulary Service

creating new content This is to ensure that the association between SDP-V content and Programs and Surveillance Systems remains accurate This association between content and the Program and System using it helps other users of the system to better understand the context in which existing SDP-V content is used and make informed decisions to reuse content for their own data collection needs

bull Authors should include in a request for draft content to be published at leastthe followingo Whenever a Response Set or Question is extended describe why the

original content did not meet the Authorrsquos needs This context couldbe valuable to other users (eg reading level culturally preferredterm etc)

o A need date for publishing the draft content

233 PUBLISHER (AUTHENTICATED USER WITH PUBLISHER ROLE) SDP-V Publishers are identified by CDC Programs as users expected to review SDP-V survey publication requests for their program area to ensure that vocabulary is harmonized to reduce redundancy in addition to add edit revise or curate program content Publishers are authenticated SDP-V users (ie Authors) who have been granted the Publisher role In general Publishers are individuals who have expertise with surveys vocabularies public health standards and the program they support They have expertise in content needed to perform surveillance for a condition or set of conditions Publishers are responsible for SDP-V content for a single program but should have a cross-program awareness of related content to encourage cross-program harmony

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see Section 7)

A summary of capabilities available to Publishers in SDP-V are as follows

2331 PUBLISHER CAPABILTIES bull Browse and search all draft contentbull Ability to publish content that is in a draft state regardless of the author of

that contentbull All Author capabilities (See Section 2321)

2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for Publishers to maximize the value of SDP-V

bull Ensure quality of questions and response sets and ensure that Authors usepre-existing authoritative response sets (eg those synchronized from PHINVADS) where possible

bull Ensure harmony of content within the assigned programbull Encourage harmony across content for multiple programs

Page 9 of 58

SDP Vocabulary Service

bull Be responsive to Author publish requestsbull Inform Author of disposition of publish request via email

234 ADMINISTRATOR (AUTHENTICATED USER WITH ADMIN ROLE) SDP-V Administrators are identified by CDC Programs Administrators are authenticated SDP-V users (ie Authors) who have been granted the Admin role Administrators are individuals who will perform various platform tasks and maintenance on behalf of the CDC

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see section 7)

2341 ADMINSTRATOR CAPABILITIES A summary of capabilities available to Administrators in SDP-V are as follows

bull Access to an Admin Panel page (more detail in Section 6)bull Ability to curate the list of Admins Publishers Programs and Systems

currently in the systembull Ability to curate the list of groups and group membership listsbull Administrative tasks involving synchronization of elasticsearchbull All Author capabilities (See Section 2321)bull All Publisher capabilities (See Section 2331)

Page 10 of 58

SDP Vocabulary Service

24 COLLABORATIVE AUTHORING GROUPS

The current version of SDP-V allows for a user with the administrator role (see 234) to create groups of authors A group should be created if multiple authors need to view and collaborate on content that is in draft workflow status (see 25) otherwise only the original author of the content would be able to view the content prior to publication Once added to an authoring group an authenticated user can add or remove content that they have created to the group Other members of the group will subsequently have all the same abilities to edit revise and maintain that content as the original author Groups allow users to collaborate with other authors while creating and revising content On a userrsquos account details page (to display account details click the userrsquos email in the top right then select ldquosettings)rdquo the user can see a list of all groups where an administrator has granted access

25 KEY TERMS

bull Tag ndash A keyword from a controlled vocabulary applied to a question section orsurvey to help facilitate finding relevant questions during a search

bull Workflow Status ndash SDP-V content can be in either a Draft or Published workflowstatus

o Draft ndash When content is created in SDP-V it is in Draft status

Visibility Content in draft workflow status is only visible to the user whoauthored it users that belong to a group that the content is added to(see section 24) and to all Publishers in the system

Ability to Modify Content Only the Author or group members maymake changes to the draft content The draft content can be edited asdesired until it is ready to be sent to a Publisher for review SDP-V trackschanges to draft content

Page 11 of 58

SDP Vocabulary Service

o Published ndash Content must be reviewed and approved by a Publisher (seeSection 233 in SDP-V to move into Published workflow status

Visibility Published content is visible to everyone who has access toSDP-V

Ability to Modify Content Only the Author or group members ofPublished content may choose to revise it This creates a new version ofthe content in draft status SDP-V maintains a version history for contentso that users can see how content has evolved over time

Note Published content is not necessarily authoritative andcontributions from external (ie outside CDC) partners should becoordinated by associated CDC programs Published content indicatesthat a program was ready to share content with others to promotetransparency harmonization standardization and the goals of SDP-VSDP-V is developing features that will be available in future release thatwill help users curate content and help programs identify preferredquestions and response sets to use in future data collection instruments

26 OPERATIONAL STATUS

The current version of SDP-V is the first major production release representing a minimally viable set of features Future releases will incorporate additional capability development based on feedback and feature requests from existing and future users

27 SECTION 508 COMPLIANCE AND ACCESIBILITY FEATURES

The current version of SDP-V has been tested according to HHS Section 508 Subparts B through D In order to meet the requirements of users requiring assistive technologies the following accessibility and compatibility features have been implemented in the application

bull Screen-reader-only text that allows the purpose of icons links and otherelements to be clear to non-sighted users

bull Skip navigation links

bull Tab index hierarchy on HTML elements that supports logical tab order to usersviewing the application with stylesheets disabled or without use of a mouse

bull Aria labels and titles where appropriate to make sure all forms and objects areaccessible through assistive technologies

bull High visibility contrast and color settings that conform to 508 standards aschecked with the WAVE compliance tool

bull In application help documentation that details all of the features of the applicationin plain ASCII text

bull Data tables with appropriately scoped column headers for screen readeraccessibility

Page 12 of 58

SDP Vocabulary Service

3 GETTING STARTED

This section serves as a quick reference for basic access and account configuration actions

31 ACCESSING SDP-V

The SDP-V service is accessible via a web browser by visiting the following URL httpssdp-vservicecdcgov A user account is not required to browse search and view content in the service that has been published A user account is required to author content or view content that is in draft status

Information on registering as a user is contained in Section 32 Information on accessing the content in the service via a Representational State Transfer (RESTFul) API is provided in Section 411 of this document

32 REGISTERING AS A USER

Authentication to the SDP-V service is provided via the CDC Secure Access Management Service (SAMS)4 If you receive an error message after entering your credentials into SAMS please email surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership If you do not have a SAMS account you will need to obtain one before you can register as a user with SDP-V

321 VIEWER If your only need is to view search and export published SDP-V content you may simply follow the access instructions in Section 31 to get started

322 AUTHOR In order to become an SDP-V Author users should work with their program leadership to request the ability to author content If you are uncertain who to contact contact the SDP program (see Section 7) for assistance Registering to become an SDP-V Author involves the prospective user accepting an invitation from SAMS providing information to CDC and review of this information by CDC Please allow time for your request to be reviewed and approved

323 PUBLISHER Because Publishers have the important duty of ensuring quality and encouraging harmonization they are identified when a CDC program commits to using SDP-V to author questions and response sets needed to address their data collection needs The SDP program calls this ldquoprogram onboardingrdquo Therefore SDP-V Publishers are normally designated by the associated CDC program during the program onboarding process After this onboarding process changes to Publishers can be made by sending an email request to the SDP program (see Section 7)

4 For more information about SAMS please visit httpsauthcdcgov

Page 13 of 58

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 2: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

VERSION HISTORY

SDP-V Release

Drafted By

Revision Date

Description of Change

10 R Dingwell A Gregorowicz

E Hathaway S Irivinti

071917 Initial Version

10 D Pellitieri 092717 Adding a description of the accessibility and compatibility features to bring document in line with 508 requirement Subpart_D_1194_41 ID 2b1

14 D Pellitieri 110817 Updating with phase 1A sprint work

14 D Pellitieri 122017 Updating with groups and end of phase 1A edits

18 K Hay 8718 Updating with phase 2 sprint work through Release 18

Page 2 of 58

SDP Vocabulary Service

TABLE OF CONTENTS

1 INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE 5

2 SDP-V GOAL 5

21 SDP-V Overview 6

22 Types of Content in SDP-V 6

23 System Roles And Capabilities Summary 8

231 Viewer (Public) 8

232 Author (Authenticated User) 8

233 Publisher (Authenticated User With Publisher Role) 9

234 Administrator (Authenticated User With Admin Role) 10

24 Collaborative Authoring Groups 11

25 Key Terms 11

26 Operational Status 12

27 Section 508 Compliance and Accesibility Features 12

3 GETTING STARTED 13

31 Accessing SDP-V 13

32 Registering as a User 13

321 Viewer 13

322 Author 13

323 Publisher 13

324 Administrator 14

33 Logging In 14

34 Selecting a Program and Surveillance System 15

35 Navigation Overview 17

36 Logging Out 18

4 INSTRUCTIONS FOR SDP-V USE 19

41 Searching for Content 19

411 Filtering By Type Of Content 20

412 Filtering To ldquoMy Stuffrdquo 21

413 Filtering By Group 22

42 Advanced Search features 22

421 Filtering By Program Surveillance System Or Both 23

422 Sorting Content 24

423 Most Recent Version Filter 25

424 Content Changed Since Filter 26

43 Viewing Details of Existing Content 28

Page 3 of 58

SDP Vocabulary Service

44 Drafting New Content 30

441 Drafting New Questions 30

442 Drafting New Response Sets 33

443 Drafting New Sections 35

444 Drafting New Surveys 37

45 Importing New Content 39

451 Message Mapping Guide (MMG) 39

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template 41

46 Revising and Editing Content 42

47 Extending Content 44

48 Adding Content to Groups 44

49 Commenting on Existing Content 45

410 Exporting Content 46

4101 Epi Info (Surveys and Sections) 46

4102 REDCap (Surveys and Sections) 46

4103 Spreadsheet (XLSX) (Surveys only) 47

4104 PDF (Surveys and Sections) 47

411 Accessing Content via the SDP-V Application Programming Interface (API) 47

412 Requesting that Content be Published 48

5 PUBLISHER FUNCTIONS 49

51 Find Othersrsquo Draft Content 49

52 Publish Draft Content 49

6 ADMINISTRATOR FUNCTIONS 50

61 Admin List amp Publisher List Tabs 50

62 Program List amp System List Tabs 50

63 Elasticsearch Tab 51

64 Group List Tab 51

7 CONTACT US 52

APPENDIX A ACRONYMS 53

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS 54

Page 4 of 58

1

2

SDP Vocabulary Service

INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE

This document serves as a reference for users of the Surveillance Data Platform (SDP) Vocabulary Service (SDP-V) on how to use the application It also provides background and context on the intent of SDP-V the types of content it contains the types of user roles and the actions users are able to take

SDP-V GOAL

The goal of SDP-V is to facilitate discovery and reuse of existing vocabulary content thereby reducing the number of different ways the Centers for Disease Control and Prevention (CDC) asks for the same type of information across programs and surveillance systems (See 12 Figure 1) This will help to reduce state tribal local and territorial (STLT) partner reporting burden as well as drive towards harmonization in data collection instruments

By making it easy for Authors to see how others have asked for certain types of information before SDP-V enables Authors to spend less time creating new data collection instruments (See 3 Figure 1) In other words by reusing what others have done before SDP-V can enhance consistency in how questions are asked and answered Not only is it easier to answer questions asked the same way this consistency also makes it easier to compare answers and see the big picture This should allow users to spend less time figuring out how to ask the right question and spend more time doing the important work of analyzing the results

Figure 1 illustrates how this goal can be achieved by using SDP-V For better clarity this diagram is available for viewing on the SDP Vocabulary Service webpage

Figure 1 - SDP-V Enables Use of Harmonized Questions and Response Sets

Page 5 of 58

SDP Vocabulary Service

21 SDP-V OVERVIEW

SDP-V provides a repository of Response Sets Questions Sections and SDP-V Surveys These content types are described in further detail in Section 22

Content in SDP-V can be created by Authors in the user interface or can be imported from spreadsheets that conform to the message mapping guide (MMG) or SDP-V generic template formats1 Value sets from the Public Health Information Network Vocabulary Access and Distribution System (PHIN VADS)2 are synchronized in SDP-V and can be searched reused and extended by Authors

These artifacts are accessible to SDP-V users via a graphical user interface (GUI) They are also available to other applications through an application programming interface (API)

22 TYPES OF CONTENT IN SDP-V

SDP-V serves as a repository and authoring tool for four different types of content Response Sets Questions Sections and SDP-V Surveys Figure 2 shows how the different types of content are related for better clarity the diagram can also be viewed on the SDP Vocabulary Service webpage

These content types are defined as follows

bull Response Set ndash A set of response choices that are applicable answers to one ormore questions

bull Question ndash Typically a natural language expression used to solicit a value for adata variable like ldquoWhat is your agerdquo In some cases like for defining vocabularyfor electronic information exchange this may be the data element name used tosolicit a value for the data variable instead of a natural language expression likeldquoSubjectrsquos Sexrdquo

o Response- A value that can be given as an answer to a question Commonresponse types include choice text and date3 Response type is a propertyof a question in SDP-V

bull Section ndash A grouping of questions related to a topic (eg demographic clinicallaboratory epidemiological) and intended to appear together as part of a datacollection instrument A section may also contain one or more sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquo and ldquoDiagnosisrdquo sectionswithin a ldquoClinicalrdquo section

bull SDP-V Survey ndash A SDP-V Survey defines the vocabulary (eg questions andresponse sets) used for a particular data collection or information exchange ASDP-V Survey contains one or more Sections that are combined together andintended for a data collection instrument or information exchange

1 Import of content may require coordination with the SDP-V development team See in-app help documentation for supported formats 2 PHIN VADS provides standard vocabularies particularly value sets associated with H7 message implementation guides to CDC and public

health partners More information about PHIN VADS can be found at httpswwwcdcgovphintoolsphinvadsindexhtml 3 A complete list of response types can be found at httpwwwhl7orgfhirvalueset-item-typehtml

Page 6 of 58

SDP Vocabulary Service

Figure 2 SDP-V Component Diagram

Page 7 of 58

SDP Vocabulary Service

23 SYSTEM ROLES AND CAPABILITIES SUMMARY

SDP-V has four defined user roles which allow access to specific content and capabilities These roles defined below include viewer author publisher and administrator In addition to these roles a user can belong to a collaborative authoring group See Section 24 for more information about groups Please see Appendix B Role Capabilities and Workflows for role capabilities and workflow flowcharts

231 VIEWER (PUBLIC) Anyone may browse published content in the Vocabulary service It is accessible to the public

232 AUTHOR (AUTHENTICATED USER) SDP-V Authors are identified by CDC Programs as users expected to add edit revise or curate program content To become an SDP-V Author users go through a CDC SDP-V onboarding process to obtain the needed credentials The SDP program calls this becoming an ldquoAuthenticated Userrdquo Users interested in becoming an Author should contact the SDP program (see Section 7)

2321 AUTHOR CAPABILITIES A summary of capabilities available to Authors in SDP-V is as follows bull Browse search and view details of all published contentbull Create new content (draft content until published)bull Import content (MMG or SDP-V template format)bull Browse and edit their own draft contentbull Browse and revise their own published contentbull Browse and extend published content Extending content creates a copy of

published content to use as a starting point for a userrsquos own contentExtending content creates a draft copy that includes a link to the content itwas extended from for traceability

bull Export contentbull Request draft content be published

2322 AUTHOR EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for the Author role to maximize the value of SDP-V

bull Authors are expected to reuse existing SDP-V content when possible toreduce variability and evolve toward harmonization Where reuse is notpractical Authors should document a justification to share with Publishers

bull When creating new Questions Sections and Surveys Authors are expectedto use Tags (see Section 44) whenever possible to make it easier for othersto search for and reuse content

bull Authors should verify that the Program and Surveillance System associatedwith their account in SDP-V (see Section 34) is accurate when they are

Page 8 of 58

SDP Vocabulary Service

creating new content This is to ensure that the association between SDP-V content and Programs and Surveillance Systems remains accurate This association between content and the Program and System using it helps other users of the system to better understand the context in which existing SDP-V content is used and make informed decisions to reuse content for their own data collection needs

bull Authors should include in a request for draft content to be published at leastthe followingo Whenever a Response Set or Question is extended describe why the

original content did not meet the Authorrsquos needs This context couldbe valuable to other users (eg reading level culturally preferredterm etc)

o A need date for publishing the draft content

233 PUBLISHER (AUTHENTICATED USER WITH PUBLISHER ROLE) SDP-V Publishers are identified by CDC Programs as users expected to review SDP-V survey publication requests for their program area to ensure that vocabulary is harmonized to reduce redundancy in addition to add edit revise or curate program content Publishers are authenticated SDP-V users (ie Authors) who have been granted the Publisher role In general Publishers are individuals who have expertise with surveys vocabularies public health standards and the program they support They have expertise in content needed to perform surveillance for a condition or set of conditions Publishers are responsible for SDP-V content for a single program but should have a cross-program awareness of related content to encourage cross-program harmony

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see Section 7)

A summary of capabilities available to Publishers in SDP-V are as follows

2331 PUBLISHER CAPABILTIES bull Browse and search all draft contentbull Ability to publish content that is in a draft state regardless of the author of

that contentbull All Author capabilities (See Section 2321)

2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for Publishers to maximize the value of SDP-V

bull Ensure quality of questions and response sets and ensure that Authors usepre-existing authoritative response sets (eg those synchronized from PHINVADS) where possible

bull Ensure harmony of content within the assigned programbull Encourage harmony across content for multiple programs

Page 9 of 58

SDP Vocabulary Service

bull Be responsive to Author publish requestsbull Inform Author of disposition of publish request via email

234 ADMINISTRATOR (AUTHENTICATED USER WITH ADMIN ROLE) SDP-V Administrators are identified by CDC Programs Administrators are authenticated SDP-V users (ie Authors) who have been granted the Admin role Administrators are individuals who will perform various platform tasks and maintenance on behalf of the CDC

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see section 7)

2341 ADMINSTRATOR CAPABILITIES A summary of capabilities available to Administrators in SDP-V are as follows

bull Access to an Admin Panel page (more detail in Section 6)bull Ability to curate the list of Admins Publishers Programs and Systems

currently in the systembull Ability to curate the list of groups and group membership listsbull Administrative tasks involving synchronization of elasticsearchbull All Author capabilities (See Section 2321)bull All Publisher capabilities (See Section 2331)

Page 10 of 58

SDP Vocabulary Service

24 COLLABORATIVE AUTHORING GROUPS

The current version of SDP-V allows for a user with the administrator role (see 234) to create groups of authors A group should be created if multiple authors need to view and collaborate on content that is in draft workflow status (see 25) otherwise only the original author of the content would be able to view the content prior to publication Once added to an authoring group an authenticated user can add or remove content that they have created to the group Other members of the group will subsequently have all the same abilities to edit revise and maintain that content as the original author Groups allow users to collaborate with other authors while creating and revising content On a userrsquos account details page (to display account details click the userrsquos email in the top right then select ldquosettings)rdquo the user can see a list of all groups where an administrator has granted access

25 KEY TERMS

bull Tag ndash A keyword from a controlled vocabulary applied to a question section orsurvey to help facilitate finding relevant questions during a search

bull Workflow Status ndash SDP-V content can be in either a Draft or Published workflowstatus

o Draft ndash When content is created in SDP-V it is in Draft status

Visibility Content in draft workflow status is only visible to the user whoauthored it users that belong to a group that the content is added to(see section 24) and to all Publishers in the system

Ability to Modify Content Only the Author or group members maymake changes to the draft content The draft content can be edited asdesired until it is ready to be sent to a Publisher for review SDP-V trackschanges to draft content

Page 11 of 58

SDP Vocabulary Service

o Published ndash Content must be reviewed and approved by a Publisher (seeSection 233 in SDP-V to move into Published workflow status

Visibility Published content is visible to everyone who has access toSDP-V

Ability to Modify Content Only the Author or group members ofPublished content may choose to revise it This creates a new version ofthe content in draft status SDP-V maintains a version history for contentso that users can see how content has evolved over time

Note Published content is not necessarily authoritative andcontributions from external (ie outside CDC) partners should becoordinated by associated CDC programs Published content indicatesthat a program was ready to share content with others to promotetransparency harmonization standardization and the goals of SDP-VSDP-V is developing features that will be available in future release thatwill help users curate content and help programs identify preferredquestions and response sets to use in future data collection instruments

26 OPERATIONAL STATUS

The current version of SDP-V is the first major production release representing a minimally viable set of features Future releases will incorporate additional capability development based on feedback and feature requests from existing and future users

27 SECTION 508 COMPLIANCE AND ACCESIBILITY FEATURES

The current version of SDP-V has been tested according to HHS Section 508 Subparts B through D In order to meet the requirements of users requiring assistive technologies the following accessibility and compatibility features have been implemented in the application

bull Screen-reader-only text that allows the purpose of icons links and otherelements to be clear to non-sighted users

bull Skip navigation links

bull Tab index hierarchy on HTML elements that supports logical tab order to usersviewing the application with stylesheets disabled or without use of a mouse

bull Aria labels and titles where appropriate to make sure all forms and objects areaccessible through assistive technologies

bull High visibility contrast and color settings that conform to 508 standards aschecked with the WAVE compliance tool

bull In application help documentation that details all of the features of the applicationin plain ASCII text

bull Data tables with appropriately scoped column headers for screen readeraccessibility

Page 12 of 58

SDP Vocabulary Service

3 GETTING STARTED

This section serves as a quick reference for basic access and account configuration actions

31 ACCESSING SDP-V

The SDP-V service is accessible via a web browser by visiting the following URL httpssdp-vservicecdcgov A user account is not required to browse search and view content in the service that has been published A user account is required to author content or view content that is in draft status

Information on registering as a user is contained in Section 32 Information on accessing the content in the service via a Representational State Transfer (RESTFul) API is provided in Section 411 of this document

32 REGISTERING AS A USER

Authentication to the SDP-V service is provided via the CDC Secure Access Management Service (SAMS)4 If you receive an error message after entering your credentials into SAMS please email surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership If you do not have a SAMS account you will need to obtain one before you can register as a user with SDP-V

321 VIEWER If your only need is to view search and export published SDP-V content you may simply follow the access instructions in Section 31 to get started

322 AUTHOR In order to become an SDP-V Author users should work with their program leadership to request the ability to author content If you are uncertain who to contact contact the SDP program (see Section 7) for assistance Registering to become an SDP-V Author involves the prospective user accepting an invitation from SAMS providing information to CDC and review of this information by CDC Please allow time for your request to be reviewed and approved

323 PUBLISHER Because Publishers have the important duty of ensuring quality and encouraging harmonization they are identified when a CDC program commits to using SDP-V to author questions and response sets needed to address their data collection needs The SDP program calls this ldquoprogram onboardingrdquo Therefore SDP-V Publishers are normally designated by the associated CDC program during the program onboarding process After this onboarding process changes to Publishers can be made by sending an email request to the SDP program (see Section 7)

4 For more information about SAMS please visit httpsauthcdcgov

Page 13 of 58

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 3: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

TABLE OF CONTENTS

1 INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE 5

2 SDP-V GOAL 5

21 SDP-V Overview 6

22 Types of Content in SDP-V 6

23 System Roles And Capabilities Summary 8

231 Viewer (Public) 8

232 Author (Authenticated User) 8

233 Publisher (Authenticated User With Publisher Role) 9

234 Administrator (Authenticated User With Admin Role) 10

24 Collaborative Authoring Groups 11

25 Key Terms 11

26 Operational Status 12

27 Section 508 Compliance and Accesibility Features 12

3 GETTING STARTED 13

31 Accessing SDP-V 13

32 Registering as a User 13

321 Viewer 13

322 Author 13

323 Publisher 13

324 Administrator 14

33 Logging In 14

34 Selecting a Program and Surveillance System 15

35 Navigation Overview 17

36 Logging Out 18

4 INSTRUCTIONS FOR SDP-V USE 19

41 Searching for Content 19

411 Filtering By Type Of Content 20

412 Filtering To ldquoMy Stuffrdquo 21

413 Filtering By Group 22

42 Advanced Search features 22

421 Filtering By Program Surveillance System Or Both 23

422 Sorting Content 24

423 Most Recent Version Filter 25

424 Content Changed Since Filter 26

43 Viewing Details of Existing Content 28

Page 3 of 58

SDP Vocabulary Service

44 Drafting New Content 30

441 Drafting New Questions 30

442 Drafting New Response Sets 33

443 Drafting New Sections 35

444 Drafting New Surveys 37

45 Importing New Content 39

451 Message Mapping Guide (MMG) 39

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template 41

46 Revising and Editing Content 42

47 Extending Content 44

48 Adding Content to Groups 44

49 Commenting on Existing Content 45

410 Exporting Content 46

4101 Epi Info (Surveys and Sections) 46

4102 REDCap (Surveys and Sections) 46

4103 Spreadsheet (XLSX) (Surveys only) 47

4104 PDF (Surveys and Sections) 47

411 Accessing Content via the SDP-V Application Programming Interface (API) 47

412 Requesting that Content be Published 48

5 PUBLISHER FUNCTIONS 49

51 Find Othersrsquo Draft Content 49

52 Publish Draft Content 49

6 ADMINISTRATOR FUNCTIONS 50

61 Admin List amp Publisher List Tabs 50

62 Program List amp System List Tabs 50

63 Elasticsearch Tab 51

64 Group List Tab 51

7 CONTACT US 52

APPENDIX A ACRONYMS 53

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS 54

Page 4 of 58

1

2

SDP Vocabulary Service

INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE

This document serves as a reference for users of the Surveillance Data Platform (SDP) Vocabulary Service (SDP-V) on how to use the application It also provides background and context on the intent of SDP-V the types of content it contains the types of user roles and the actions users are able to take

SDP-V GOAL

The goal of SDP-V is to facilitate discovery and reuse of existing vocabulary content thereby reducing the number of different ways the Centers for Disease Control and Prevention (CDC) asks for the same type of information across programs and surveillance systems (See 12 Figure 1) This will help to reduce state tribal local and territorial (STLT) partner reporting burden as well as drive towards harmonization in data collection instruments

By making it easy for Authors to see how others have asked for certain types of information before SDP-V enables Authors to spend less time creating new data collection instruments (See 3 Figure 1) In other words by reusing what others have done before SDP-V can enhance consistency in how questions are asked and answered Not only is it easier to answer questions asked the same way this consistency also makes it easier to compare answers and see the big picture This should allow users to spend less time figuring out how to ask the right question and spend more time doing the important work of analyzing the results

Figure 1 illustrates how this goal can be achieved by using SDP-V For better clarity this diagram is available for viewing on the SDP Vocabulary Service webpage

Figure 1 - SDP-V Enables Use of Harmonized Questions and Response Sets

Page 5 of 58

SDP Vocabulary Service

21 SDP-V OVERVIEW

SDP-V provides a repository of Response Sets Questions Sections and SDP-V Surveys These content types are described in further detail in Section 22

Content in SDP-V can be created by Authors in the user interface or can be imported from spreadsheets that conform to the message mapping guide (MMG) or SDP-V generic template formats1 Value sets from the Public Health Information Network Vocabulary Access and Distribution System (PHIN VADS)2 are synchronized in SDP-V and can be searched reused and extended by Authors

These artifacts are accessible to SDP-V users via a graphical user interface (GUI) They are also available to other applications through an application programming interface (API)

22 TYPES OF CONTENT IN SDP-V

SDP-V serves as a repository and authoring tool for four different types of content Response Sets Questions Sections and SDP-V Surveys Figure 2 shows how the different types of content are related for better clarity the diagram can also be viewed on the SDP Vocabulary Service webpage

These content types are defined as follows

bull Response Set ndash A set of response choices that are applicable answers to one ormore questions

bull Question ndash Typically a natural language expression used to solicit a value for adata variable like ldquoWhat is your agerdquo In some cases like for defining vocabularyfor electronic information exchange this may be the data element name used tosolicit a value for the data variable instead of a natural language expression likeldquoSubjectrsquos Sexrdquo

o Response- A value that can be given as an answer to a question Commonresponse types include choice text and date3 Response type is a propertyof a question in SDP-V

bull Section ndash A grouping of questions related to a topic (eg demographic clinicallaboratory epidemiological) and intended to appear together as part of a datacollection instrument A section may also contain one or more sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquo and ldquoDiagnosisrdquo sectionswithin a ldquoClinicalrdquo section

bull SDP-V Survey ndash A SDP-V Survey defines the vocabulary (eg questions andresponse sets) used for a particular data collection or information exchange ASDP-V Survey contains one or more Sections that are combined together andintended for a data collection instrument or information exchange

1 Import of content may require coordination with the SDP-V development team See in-app help documentation for supported formats 2 PHIN VADS provides standard vocabularies particularly value sets associated with H7 message implementation guides to CDC and public

health partners More information about PHIN VADS can be found at httpswwwcdcgovphintoolsphinvadsindexhtml 3 A complete list of response types can be found at httpwwwhl7orgfhirvalueset-item-typehtml

Page 6 of 58

SDP Vocabulary Service

Figure 2 SDP-V Component Diagram

Page 7 of 58

SDP Vocabulary Service

23 SYSTEM ROLES AND CAPABILITIES SUMMARY

SDP-V has four defined user roles which allow access to specific content and capabilities These roles defined below include viewer author publisher and administrator In addition to these roles a user can belong to a collaborative authoring group See Section 24 for more information about groups Please see Appendix B Role Capabilities and Workflows for role capabilities and workflow flowcharts

231 VIEWER (PUBLIC) Anyone may browse published content in the Vocabulary service It is accessible to the public

232 AUTHOR (AUTHENTICATED USER) SDP-V Authors are identified by CDC Programs as users expected to add edit revise or curate program content To become an SDP-V Author users go through a CDC SDP-V onboarding process to obtain the needed credentials The SDP program calls this becoming an ldquoAuthenticated Userrdquo Users interested in becoming an Author should contact the SDP program (see Section 7)

2321 AUTHOR CAPABILITIES A summary of capabilities available to Authors in SDP-V is as follows bull Browse search and view details of all published contentbull Create new content (draft content until published)bull Import content (MMG or SDP-V template format)bull Browse and edit their own draft contentbull Browse and revise their own published contentbull Browse and extend published content Extending content creates a copy of

published content to use as a starting point for a userrsquos own contentExtending content creates a draft copy that includes a link to the content itwas extended from for traceability

bull Export contentbull Request draft content be published

2322 AUTHOR EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for the Author role to maximize the value of SDP-V

bull Authors are expected to reuse existing SDP-V content when possible toreduce variability and evolve toward harmonization Where reuse is notpractical Authors should document a justification to share with Publishers

bull When creating new Questions Sections and Surveys Authors are expectedto use Tags (see Section 44) whenever possible to make it easier for othersto search for and reuse content

bull Authors should verify that the Program and Surveillance System associatedwith their account in SDP-V (see Section 34) is accurate when they are

Page 8 of 58

SDP Vocabulary Service

creating new content This is to ensure that the association between SDP-V content and Programs and Surveillance Systems remains accurate This association between content and the Program and System using it helps other users of the system to better understand the context in which existing SDP-V content is used and make informed decisions to reuse content for their own data collection needs

bull Authors should include in a request for draft content to be published at leastthe followingo Whenever a Response Set or Question is extended describe why the

original content did not meet the Authorrsquos needs This context couldbe valuable to other users (eg reading level culturally preferredterm etc)

o A need date for publishing the draft content

233 PUBLISHER (AUTHENTICATED USER WITH PUBLISHER ROLE) SDP-V Publishers are identified by CDC Programs as users expected to review SDP-V survey publication requests for their program area to ensure that vocabulary is harmonized to reduce redundancy in addition to add edit revise or curate program content Publishers are authenticated SDP-V users (ie Authors) who have been granted the Publisher role In general Publishers are individuals who have expertise with surveys vocabularies public health standards and the program they support They have expertise in content needed to perform surveillance for a condition or set of conditions Publishers are responsible for SDP-V content for a single program but should have a cross-program awareness of related content to encourage cross-program harmony

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see Section 7)

A summary of capabilities available to Publishers in SDP-V are as follows

2331 PUBLISHER CAPABILTIES bull Browse and search all draft contentbull Ability to publish content that is in a draft state regardless of the author of

that contentbull All Author capabilities (See Section 2321)

2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for Publishers to maximize the value of SDP-V

bull Ensure quality of questions and response sets and ensure that Authors usepre-existing authoritative response sets (eg those synchronized from PHINVADS) where possible

bull Ensure harmony of content within the assigned programbull Encourage harmony across content for multiple programs

Page 9 of 58

SDP Vocabulary Service

bull Be responsive to Author publish requestsbull Inform Author of disposition of publish request via email

234 ADMINISTRATOR (AUTHENTICATED USER WITH ADMIN ROLE) SDP-V Administrators are identified by CDC Programs Administrators are authenticated SDP-V users (ie Authors) who have been granted the Admin role Administrators are individuals who will perform various platform tasks and maintenance on behalf of the CDC

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see section 7)

2341 ADMINSTRATOR CAPABILITIES A summary of capabilities available to Administrators in SDP-V are as follows

bull Access to an Admin Panel page (more detail in Section 6)bull Ability to curate the list of Admins Publishers Programs and Systems

currently in the systembull Ability to curate the list of groups and group membership listsbull Administrative tasks involving synchronization of elasticsearchbull All Author capabilities (See Section 2321)bull All Publisher capabilities (See Section 2331)

Page 10 of 58

SDP Vocabulary Service

24 COLLABORATIVE AUTHORING GROUPS

The current version of SDP-V allows for a user with the administrator role (see 234) to create groups of authors A group should be created if multiple authors need to view and collaborate on content that is in draft workflow status (see 25) otherwise only the original author of the content would be able to view the content prior to publication Once added to an authoring group an authenticated user can add or remove content that they have created to the group Other members of the group will subsequently have all the same abilities to edit revise and maintain that content as the original author Groups allow users to collaborate with other authors while creating and revising content On a userrsquos account details page (to display account details click the userrsquos email in the top right then select ldquosettings)rdquo the user can see a list of all groups where an administrator has granted access

25 KEY TERMS

bull Tag ndash A keyword from a controlled vocabulary applied to a question section orsurvey to help facilitate finding relevant questions during a search

bull Workflow Status ndash SDP-V content can be in either a Draft or Published workflowstatus

o Draft ndash When content is created in SDP-V it is in Draft status

Visibility Content in draft workflow status is only visible to the user whoauthored it users that belong to a group that the content is added to(see section 24) and to all Publishers in the system

Ability to Modify Content Only the Author or group members maymake changes to the draft content The draft content can be edited asdesired until it is ready to be sent to a Publisher for review SDP-V trackschanges to draft content

Page 11 of 58

SDP Vocabulary Service

o Published ndash Content must be reviewed and approved by a Publisher (seeSection 233 in SDP-V to move into Published workflow status

Visibility Published content is visible to everyone who has access toSDP-V

Ability to Modify Content Only the Author or group members ofPublished content may choose to revise it This creates a new version ofthe content in draft status SDP-V maintains a version history for contentso that users can see how content has evolved over time

Note Published content is not necessarily authoritative andcontributions from external (ie outside CDC) partners should becoordinated by associated CDC programs Published content indicatesthat a program was ready to share content with others to promotetransparency harmonization standardization and the goals of SDP-VSDP-V is developing features that will be available in future release thatwill help users curate content and help programs identify preferredquestions and response sets to use in future data collection instruments

26 OPERATIONAL STATUS

The current version of SDP-V is the first major production release representing a minimally viable set of features Future releases will incorporate additional capability development based on feedback and feature requests from existing and future users

27 SECTION 508 COMPLIANCE AND ACCESIBILITY FEATURES

The current version of SDP-V has been tested according to HHS Section 508 Subparts B through D In order to meet the requirements of users requiring assistive technologies the following accessibility and compatibility features have been implemented in the application

bull Screen-reader-only text that allows the purpose of icons links and otherelements to be clear to non-sighted users

bull Skip navigation links

bull Tab index hierarchy on HTML elements that supports logical tab order to usersviewing the application with stylesheets disabled or without use of a mouse

bull Aria labels and titles where appropriate to make sure all forms and objects areaccessible through assistive technologies

bull High visibility contrast and color settings that conform to 508 standards aschecked with the WAVE compliance tool

bull In application help documentation that details all of the features of the applicationin plain ASCII text

bull Data tables with appropriately scoped column headers for screen readeraccessibility

Page 12 of 58

SDP Vocabulary Service

3 GETTING STARTED

This section serves as a quick reference for basic access and account configuration actions

31 ACCESSING SDP-V

The SDP-V service is accessible via a web browser by visiting the following URL httpssdp-vservicecdcgov A user account is not required to browse search and view content in the service that has been published A user account is required to author content or view content that is in draft status

Information on registering as a user is contained in Section 32 Information on accessing the content in the service via a Representational State Transfer (RESTFul) API is provided in Section 411 of this document

32 REGISTERING AS A USER

Authentication to the SDP-V service is provided via the CDC Secure Access Management Service (SAMS)4 If you receive an error message after entering your credentials into SAMS please email surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership If you do not have a SAMS account you will need to obtain one before you can register as a user with SDP-V

321 VIEWER If your only need is to view search and export published SDP-V content you may simply follow the access instructions in Section 31 to get started

322 AUTHOR In order to become an SDP-V Author users should work with their program leadership to request the ability to author content If you are uncertain who to contact contact the SDP program (see Section 7) for assistance Registering to become an SDP-V Author involves the prospective user accepting an invitation from SAMS providing information to CDC and review of this information by CDC Please allow time for your request to be reviewed and approved

323 PUBLISHER Because Publishers have the important duty of ensuring quality and encouraging harmonization they are identified when a CDC program commits to using SDP-V to author questions and response sets needed to address their data collection needs The SDP program calls this ldquoprogram onboardingrdquo Therefore SDP-V Publishers are normally designated by the associated CDC program during the program onboarding process After this onboarding process changes to Publishers can be made by sending an email request to the SDP program (see Section 7)

4 For more information about SAMS please visit httpsauthcdcgov

Page 13 of 58

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 4: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

44 Drafting New Content 30

441 Drafting New Questions 30

442 Drafting New Response Sets 33

443 Drafting New Sections 35

444 Drafting New Surveys 37

45 Importing New Content 39

451 Message Mapping Guide (MMG) 39

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template 41

46 Revising and Editing Content 42

47 Extending Content 44

48 Adding Content to Groups 44

49 Commenting on Existing Content 45

410 Exporting Content 46

4101 Epi Info (Surveys and Sections) 46

4102 REDCap (Surveys and Sections) 46

4103 Spreadsheet (XLSX) (Surveys only) 47

4104 PDF (Surveys and Sections) 47

411 Accessing Content via the SDP-V Application Programming Interface (API) 47

412 Requesting that Content be Published 48

5 PUBLISHER FUNCTIONS 49

51 Find Othersrsquo Draft Content 49

52 Publish Draft Content 49

6 ADMINISTRATOR FUNCTIONS 50

61 Admin List amp Publisher List Tabs 50

62 Program List amp System List Tabs 50

63 Elasticsearch Tab 51

64 Group List Tab 51

7 CONTACT US 52

APPENDIX A ACRONYMS 53

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS 54

Page 4 of 58

1

2

SDP Vocabulary Service

INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE

This document serves as a reference for users of the Surveillance Data Platform (SDP) Vocabulary Service (SDP-V) on how to use the application It also provides background and context on the intent of SDP-V the types of content it contains the types of user roles and the actions users are able to take

SDP-V GOAL

The goal of SDP-V is to facilitate discovery and reuse of existing vocabulary content thereby reducing the number of different ways the Centers for Disease Control and Prevention (CDC) asks for the same type of information across programs and surveillance systems (See 12 Figure 1) This will help to reduce state tribal local and territorial (STLT) partner reporting burden as well as drive towards harmonization in data collection instruments

By making it easy for Authors to see how others have asked for certain types of information before SDP-V enables Authors to spend less time creating new data collection instruments (See 3 Figure 1) In other words by reusing what others have done before SDP-V can enhance consistency in how questions are asked and answered Not only is it easier to answer questions asked the same way this consistency also makes it easier to compare answers and see the big picture This should allow users to spend less time figuring out how to ask the right question and spend more time doing the important work of analyzing the results

Figure 1 illustrates how this goal can be achieved by using SDP-V For better clarity this diagram is available for viewing on the SDP Vocabulary Service webpage

Figure 1 - SDP-V Enables Use of Harmonized Questions and Response Sets

Page 5 of 58

SDP Vocabulary Service

21 SDP-V OVERVIEW

SDP-V provides a repository of Response Sets Questions Sections and SDP-V Surveys These content types are described in further detail in Section 22

Content in SDP-V can be created by Authors in the user interface or can be imported from spreadsheets that conform to the message mapping guide (MMG) or SDP-V generic template formats1 Value sets from the Public Health Information Network Vocabulary Access and Distribution System (PHIN VADS)2 are synchronized in SDP-V and can be searched reused and extended by Authors

These artifacts are accessible to SDP-V users via a graphical user interface (GUI) They are also available to other applications through an application programming interface (API)

22 TYPES OF CONTENT IN SDP-V

SDP-V serves as a repository and authoring tool for four different types of content Response Sets Questions Sections and SDP-V Surveys Figure 2 shows how the different types of content are related for better clarity the diagram can also be viewed on the SDP Vocabulary Service webpage

These content types are defined as follows

bull Response Set ndash A set of response choices that are applicable answers to one ormore questions

bull Question ndash Typically a natural language expression used to solicit a value for adata variable like ldquoWhat is your agerdquo In some cases like for defining vocabularyfor electronic information exchange this may be the data element name used tosolicit a value for the data variable instead of a natural language expression likeldquoSubjectrsquos Sexrdquo

o Response- A value that can be given as an answer to a question Commonresponse types include choice text and date3 Response type is a propertyof a question in SDP-V

bull Section ndash A grouping of questions related to a topic (eg demographic clinicallaboratory epidemiological) and intended to appear together as part of a datacollection instrument A section may also contain one or more sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquo and ldquoDiagnosisrdquo sectionswithin a ldquoClinicalrdquo section

bull SDP-V Survey ndash A SDP-V Survey defines the vocabulary (eg questions andresponse sets) used for a particular data collection or information exchange ASDP-V Survey contains one or more Sections that are combined together andintended for a data collection instrument or information exchange

1 Import of content may require coordination with the SDP-V development team See in-app help documentation for supported formats 2 PHIN VADS provides standard vocabularies particularly value sets associated with H7 message implementation guides to CDC and public

health partners More information about PHIN VADS can be found at httpswwwcdcgovphintoolsphinvadsindexhtml 3 A complete list of response types can be found at httpwwwhl7orgfhirvalueset-item-typehtml

Page 6 of 58

SDP Vocabulary Service

Figure 2 SDP-V Component Diagram

Page 7 of 58

SDP Vocabulary Service

23 SYSTEM ROLES AND CAPABILITIES SUMMARY

SDP-V has four defined user roles which allow access to specific content and capabilities These roles defined below include viewer author publisher and administrator In addition to these roles a user can belong to a collaborative authoring group See Section 24 for more information about groups Please see Appendix B Role Capabilities and Workflows for role capabilities and workflow flowcharts

231 VIEWER (PUBLIC) Anyone may browse published content in the Vocabulary service It is accessible to the public

232 AUTHOR (AUTHENTICATED USER) SDP-V Authors are identified by CDC Programs as users expected to add edit revise or curate program content To become an SDP-V Author users go through a CDC SDP-V onboarding process to obtain the needed credentials The SDP program calls this becoming an ldquoAuthenticated Userrdquo Users interested in becoming an Author should contact the SDP program (see Section 7)

2321 AUTHOR CAPABILITIES A summary of capabilities available to Authors in SDP-V is as follows bull Browse search and view details of all published contentbull Create new content (draft content until published)bull Import content (MMG or SDP-V template format)bull Browse and edit their own draft contentbull Browse and revise their own published contentbull Browse and extend published content Extending content creates a copy of

published content to use as a starting point for a userrsquos own contentExtending content creates a draft copy that includes a link to the content itwas extended from for traceability

bull Export contentbull Request draft content be published

2322 AUTHOR EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for the Author role to maximize the value of SDP-V

bull Authors are expected to reuse existing SDP-V content when possible toreduce variability and evolve toward harmonization Where reuse is notpractical Authors should document a justification to share with Publishers

bull When creating new Questions Sections and Surveys Authors are expectedto use Tags (see Section 44) whenever possible to make it easier for othersto search for and reuse content

bull Authors should verify that the Program and Surveillance System associatedwith their account in SDP-V (see Section 34) is accurate when they are

Page 8 of 58

SDP Vocabulary Service

creating new content This is to ensure that the association between SDP-V content and Programs and Surveillance Systems remains accurate This association between content and the Program and System using it helps other users of the system to better understand the context in which existing SDP-V content is used and make informed decisions to reuse content for their own data collection needs

bull Authors should include in a request for draft content to be published at leastthe followingo Whenever a Response Set or Question is extended describe why the

original content did not meet the Authorrsquos needs This context couldbe valuable to other users (eg reading level culturally preferredterm etc)

o A need date for publishing the draft content

233 PUBLISHER (AUTHENTICATED USER WITH PUBLISHER ROLE) SDP-V Publishers are identified by CDC Programs as users expected to review SDP-V survey publication requests for their program area to ensure that vocabulary is harmonized to reduce redundancy in addition to add edit revise or curate program content Publishers are authenticated SDP-V users (ie Authors) who have been granted the Publisher role In general Publishers are individuals who have expertise with surveys vocabularies public health standards and the program they support They have expertise in content needed to perform surveillance for a condition or set of conditions Publishers are responsible for SDP-V content for a single program but should have a cross-program awareness of related content to encourage cross-program harmony

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see Section 7)

A summary of capabilities available to Publishers in SDP-V are as follows

2331 PUBLISHER CAPABILTIES bull Browse and search all draft contentbull Ability to publish content that is in a draft state regardless of the author of

that contentbull All Author capabilities (See Section 2321)

2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for Publishers to maximize the value of SDP-V

bull Ensure quality of questions and response sets and ensure that Authors usepre-existing authoritative response sets (eg those synchronized from PHINVADS) where possible

bull Ensure harmony of content within the assigned programbull Encourage harmony across content for multiple programs

Page 9 of 58

SDP Vocabulary Service

bull Be responsive to Author publish requestsbull Inform Author of disposition of publish request via email

234 ADMINISTRATOR (AUTHENTICATED USER WITH ADMIN ROLE) SDP-V Administrators are identified by CDC Programs Administrators are authenticated SDP-V users (ie Authors) who have been granted the Admin role Administrators are individuals who will perform various platform tasks and maintenance on behalf of the CDC

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see section 7)

2341 ADMINSTRATOR CAPABILITIES A summary of capabilities available to Administrators in SDP-V are as follows

bull Access to an Admin Panel page (more detail in Section 6)bull Ability to curate the list of Admins Publishers Programs and Systems

currently in the systembull Ability to curate the list of groups and group membership listsbull Administrative tasks involving synchronization of elasticsearchbull All Author capabilities (See Section 2321)bull All Publisher capabilities (See Section 2331)

Page 10 of 58

SDP Vocabulary Service

24 COLLABORATIVE AUTHORING GROUPS

The current version of SDP-V allows for a user with the administrator role (see 234) to create groups of authors A group should be created if multiple authors need to view and collaborate on content that is in draft workflow status (see 25) otherwise only the original author of the content would be able to view the content prior to publication Once added to an authoring group an authenticated user can add or remove content that they have created to the group Other members of the group will subsequently have all the same abilities to edit revise and maintain that content as the original author Groups allow users to collaborate with other authors while creating and revising content On a userrsquos account details page (to display account details click the userrsquos email in the top right then select ldquosettings)rdquo the user can see a list of all groups where an administrator has granted access

25 KEY TERMS

bull Tag ndash A keyword from a controlled vocabulary applied to a question section orsurvey to help facilitate finding relevant questions during a search

bull Workflow Status ndash SDP-V content can be in either a Draft or Published workflowstatus

o Draft ndash When content is created in SDP-V it is in Draft status

Visibility Content in draft workflow status is only visible to the user whoauthored it users that belong to a group that the content is added to(see section 24) and to all Publishers in the system

Ability to Modify Content Only the Author or group members maymake changes to the draft content The draft content can be edited asdesired until it is ready to be sent to a Publisher for review SDP-V trackschanges to draft content

Page 11 of 58

SDP Vocabulary Service

o Published ndash Content must be reviewed and approved by a Publisher (seeSection 233 in SDP-V to move into Published workflow status

Visibility Published content is visible to everyone who has access toSDP-V

Ability to Modify Content Only the Author or group members ofPublished content may choose to revise it This creates a new version ofthe content in draft status SDP-V maintains a version history for contentso that users can see how content has evolved over time

Note Published content is not necessarily authoritative andcontributions from external (ie outside CDC) partners should becoordinated by associated CDC programs Published content indicatesthat a program was ready to share content with others to promotetransparency harmonization standardization and the goals of SDP-VSDP-V is developing features that will be available in future release thatwill help users curate content and help programs identify preferredquestions and response sets to use in future data collection instruments

26 OPERATIONAL STATUS

The current version of SDP-V is the first major production release representing a minimally viable set of features Future releases will incorporate additional capability development based on feedback and feature requests from existing and future users

27 SECTION 508 COMPLIANCE AND ACCESIBILITY FEATURES

The current version of SDP-V has been tested according to HHS Section 508 Subparts B through D In order to meet the requirements of users requiring assistive technologies the following accessibility and compatibility features have been implemented in the application

bull Screen-reader-only text that allows the purpose of icons links and otherelements to be clear to non-sighted users

bull Skip navigation links

bull Tab index hierarchy on HTML elements that supports logical tab order to usersviewing the application with stylesheets disabled or without use of a mouse

bull Aria labels and titles where appropriate to make sure all forms and objects areaccessible through assistive technologies

bull High visibility contrast and color settings that conform to 508 standards aschecked with the WAVE compliance tool

bull In application help documentation that details all of the features of the applicationin plain ASCII text

bull Data tables with appropriately scoped column headers for screen readeraccessibility

Page 12 of 58

SDP Vocabulary Service

3 GETTING STARTED

This section serves as a quick reference for basic access and account configuration actions

31 ACCESSING SDP-V

The SDP-V service is accessible via a web browser by visiting the following URL httpssdp-vservicecdcgov A user account is not required to browse search and view content in the service that has been published A user account is required to author content or view content that is in draft status

Information on registering as a user is contained in Section 32 Information on accessing the content in the service via a Representational State Transfer (RESTFul) API is provided in Section 411 of this document

32 REGISTERING AS A USER

Authentication to the SDP-V service is provided via the CDC Secure Access Management Service (SAMS)4 If you receive an error message after entering your credentials into SAMS please email surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership If you do not have a SAMS account you will need to obtain one before you can register as a user with SDP-V

321 VIEWER If your only need is to view search and export published SDP-V content you may simply follow the access instructions in Section 31 to get started

322 AUTHOR In order to become an SDP-V Author users should work with their program leadership to request the ability to author content If you are uncertain who to contact contact the SDP program (see Section 7) for assistance Registering to become an SDP-V Author involves the prospective user accepting an invitation from SAMS providing information to CDC and review of this information by CDC Please allow time for your request to be reviewed and approved

323 PUBLISHER Because Publishers have the important duty of ensuring quality and encouraging harmonization they are identified when a CDC program commits to using SDP-V to author questions and response sets needed to address their data collection needs The SDP program calls this ldquoprogram onboardingrdquo Therefore SDP-V Publishers are normally designated by the associated CDC program during the program onboarding process After this onboarding process changes to Publishers can be made by sending an email request to the SDP program (see Section 7)

4 For more information about SAMS please visit httpsauthcdcgov

Page 13 of 58

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 5: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

1

2

SDP Vocabulary Service

INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE

This document serves as a reference for users of the Surveillance Data Platform (SDP) Vocabulary Service (SDP-V) on how to use the application It also provides background and context on the intent of SDP-V the types of content it contains the types of user roles and the actions users are able to take

SDP-V GOAL

The goal of SDP-V is to facilitate discovery and reuse of existing vocabulary content thereby reducing the number of different ways the Centers for Disease Control and Prevention (CDC) asks for the same type of information across programs and surveillance systems (See 12 Figure 1) This will help to reduce state tribal local and territorial (STLT) partner reporting burden as well as drive towards harmonization in data collection instruments

By making it easy for Authors to see how others have asked for certain types of information before SDP-V enables Authors to spend less time creating new data collection instruments (See 3 Figure 1) In other words by reusing what others have done before SDP-V can enhance consistency in how questions are asked and answered Not only is it easier to answer questions asked the same way this consistency also makes it easier to compare answers and see the big picture This should allow users to spend less time figuring out how to ask the right question and spend more time doing the important work of analyzing the results

Figure 1 illustrates how this goal can be achieved by using SDP-V For better clarity this diagram is available for viewing on the SDP Vocabulary Service webpage

Figure 1 - SDP-V Enables Use of Harmonized Questions and Response Sets

Page 5 of 58

SDP Vocabulary Service

21 SDP-V OVERVIEW

SDP-V provides a repository of Response Sets Questions Sections and SDP-V Surveys These content types are described in further detail in Section 22

Content in SDP-V can be created by Authors in the user interface or can be imported from spreadsheets that conform to the message mapping guide (MMG) or SDP-V generic template formats1 Value sets from the Public Health Information Network Vocabulary Access and Distribution System (PHIN VADS)2 are synchronized in SDP-V and can be searched reused and extended by Authors

These artifacts are accessible to SDP-V users via a graphical user interface (GUI) They are also available to other applications through an application programming interface (API)

22 TYPES OF CONTENT IN SDP-V

SDP-V serves as a repository and authoring tool for four different types of content Response Sets Questions Sections and SDP-V Surveys Figure 2 shows how the different types of content are related for better clarity the diagram can also be viewed on the SDP Vocabulary Service webpage

These content types are defined as follows

bull Response Set ndash A set of response choices that are applicable answers to one ormore questions

bull Question ndash Typically a natural language expression used to solicit a value for adata variable like ldquoWhat is your agerdquo In some cases like for defining vocabularyfor electronic information exchange this may be the data element name used tosolicit a value for the data variable instead of a natural language expression likeldquoSubjectrsquos Sexrdquo

o Response- A value that can be given as an answer to a question Commonresponse types include choice text and date3 Response type is a propertyof a question in SDP-V

bull Section ndash A grouping of questions related to a topic (eg demographic clinicallaboratory epidemiological) and intended to appear together as part of a datacollection instrument A section may also contain one or more sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquo and ldquoDiagnosisrdquo sectionswithin a ldquoClinicalrdquo section

bull SDP-V Survey ndash A SDP-V Survey defines the vocabulary (eg questions andresponse sets) used for a particular data collection or information exchange ASDP-V Survey contains one or more Sections that are combined together andintended for a data collection instrument or information exchange

1 Import of content may require coordination with the SDP-V development team See in-app help documentation for supported formats 2 PHIN VADS provides standard vocabularies particularly value sets associated with H7 message implementation guides to CDC and public

health partners More information about PHIN VADS can be found at httpswwwcdcgovphintoolsphinvadsindexhtml 3 A complete list of response types can be found at httpwwwhl7orgfhirvalueset-item-typehtml

Page 6 of 58

SDP Vocabulary Service

Figure 2 SDP-V Component Diagram

Page 7 of 58

SDP Vocabulary Service

23 SYSTEM ROLES AND CAPABILITIES SUMMARY

SDP-V has four defined user roles which allow access to specific content and capabilities These roles defined below include viewer author publisher and administrator In addition to these roles a user can belong to a collaborative authoring group See Section 24 for more information about groups Please see Appendix B Role Capabilities and Workflows for role capabilities and workflow flowcharts

231 VIEWER (PUBLIC) Anyone may browse published content in the Vocabulary service It is accessible to the public

232 AUTHOR (AUTHENTICATED USER) SDP-V Authors are identified by CDC Programs as users expected to add edit revise or curate program content To become an SDP-V Author users go through a CDC SDP-V onboarding process to obtain the needed credentials The SDP program calls this becoming an ldquoAuthenticated Userrdquo Users interested in becoming an Author should contact the SDP program (see Section 7)

2321 AUTHOR CAPABILITIES A summary of capabilities available to Authors in SDP-V is as follows bull Browse search and view details of all published contentbull Create new content (draft content until published)bull Import content (MMG or SDP-V template format)bull Browse and edit their own draft contentbull Browse and revise their own published contentbull Browse and extend published content Extending content creates a copy of

published content to use as a starting point for a userrsquos own contentExtending content creates a draft copy that includes a link to the content itwas extended from for traceability

bull Export contentbull Request draft content be published

2322 AUTHOR EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for the Author role to maximize the value of SDP-V

bull Authors are expected to reuse existing SDP-V content when possible toreduce variability and evolve toward harmonization Where reuse is notpractical Authors should document a justification to share with Publishers

bull When creating new Questions Sections and Surveys Authors are expectedto use Tags (see Section 44) whenever possible to make it easier for othersto search for and reuse content

bull Authors should verify that the Program and Surveillance System associatedwith their account in SDP-V (see Section 34) is accurate when they are

Page 8 of 58

SDP Vocabulary Service

creating new content This is to ensure that the association between SDP-V content and Programs and Surveillance Systems remains accurate This association between content and the Program and System using it helps other users of the system to better understand the context in which existing SDP-V content is used and make informed decisions to reuse content for their own data collection needs

bull Authors should include in a request for draft content to be published at leastthe followingo Whenever a Response Set or Question is extended describe why the

original content did not meet the Authorrsquos needs This context couldbe valuable to other users (eg reading level culturally preferredterm etc)

o A need date for publishing the draft content

233 PUBLISHER (AUTHENTICATED USER WITH PUBLISHER ROLE) SDP-V Publishers are identified by CDC Programs as users expected to review SDP-V survey publication requests for their program area to ensure that vocabulary is harmonized to reduce redundancy in addition to add edit revise or curate program content Publishers are authenticated SDP-V users (ie Authors) who have been granted the Publisher role In general Publishers are individuals who have expertise with surveys vocabularies public health standards and the program they support They have expertise in content needed to perform surveillance for a condition or set of conditions Publishers are responsible for SDP-V content for a single program but should have a cross-program awareness of related content to encourage cross-program harmony

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see Section 7)

A summary of capabilities available to Publishers in SDP-V are as follows

2331 PUBLISHER CAPABILTIES bull Browse and search all draft contentbull Ability to publish content that is in a draft state regardless of the author of

that contentbull All Author capabilities (See Section 2321)

2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for Publishers to maximize the value of SDP-V

bull Ensure quality of questions and response sets and ensure that Authors usepre-existing authoritative response sets (eg those synchronized from PHINVADS) where possible

bull Ensure harmony of content within the assigned programbull Encourage harmony across content for multiple programs

Page 9 of 58

SDP Vocabulary Service

bull Be responsive to Author publish requestsbull Inform Author of disposition of publish request via email

234 ADMINISTRATOR (AUTHENTICATED USER WITH ADMIN ROLE) SDP-V Administrators are identified by CDC Programs Administrators are authenticated SDP-V users (ie Authors) who have been granted the Admin role Administrators are individuals who will perform various platform tasks and maintenance on behalf of the CDC

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see section 7)

2341 ADMINSTRATOR CAPABILITIES A summary of capabilities available to Administrators in SDP-V are as follows

bull Access to an Admin Panel page (more detail in Section 6)bull Ability to curate the list of Admins Publishers Programs and Systems

currently in the systembull Ability to curate the list of groups and group membership listsbull Administrative tasks involving synchronization of elasticsearchbull All Author capabilities (See Section 2321)bull All Publisher capabilities (See Section 2331)

Page 10 of 58

SDP Vocabulary Service

24 COLLABORATIVE AUTHORING GROUPS

The current version of SDP-V allows for a user with the administrator role (see 234) to create groups of authors A group should be created if multiple authors need to view and collaborate on content that is in draft workflow status (see 25) otherwise only the original author of the content would be able to view the content prior to publication Once added to an authoring group an authenticated user can add or remove content that they have created to the group Other members of the group will subsequently have all the same abilities to edit revise and maintain that content as the original author Groups allow users to collaborate with other authors while creating and revising content On a userrsquos account details page (to display account details click the userrsquos email in the top right then select ldquosettings)rdquo the user can see a list of all groups where an administrator has granted access

25 KEY TERMS

bull Tag ndash A keyword from a controlled vocabulary applied to a question section orsurvey to help facilitate finding relevant questions during a search

bull Workflow Status ndash SDP-V content can be in either a Draft or Published workflowstatus

o Draft ndash When content is created in SDP-V it is in Draft status

Visibility Content in draft workflow status is only visible to the user whoauthored it users that belong to a group that the content is added to(see section 24) and to all Publishers in the system

Ability to Modify Content Only the Author or group members maymake changes to the draft content The draft content can be edited asdesired until it is ready to be sent to a Publisher for review SDP-V trackschanges to draft content

Page 11 of 58

SDP Vocabulary Service

o Published ndash Content must be reviewed and approved by a Publisher (seeSection 233 in SDP-V to move into Published workflow status

Visibility Published content is visible to everyone who has access toSDP-V

Ability to Modify Content Only the Author or group members ofPublished content may choose to revise it This creates a new version ofthe content in draft status SDP-V maintains a version history for contentso that users can see how content has evolved over time

Note Published content is not necessarily authoritative andcontributions from external (ie outside CDC) partners should becoordinated by associated CDC programs Published content indicatesthat a program was ready to share content with others to promotetransparency harmonization standardization and the goals of SDP-VSDP-V is developing features that will be available in future release thatwill help users curate content and help programs identify preferredquestions and response sets to use in future data collection instruments

26 OPERATIONAL STATUS

The current version of SDP-V is the first major production release representing a minimally viable set of features Future releases will incorporate additional capability development based on feedback and feature requests from existing and future users

27 SECTION 508 COMPLIANCE AND ACCESIBILITY FEATURES

The current version of SDP-V has been tested according to HHS Section 508 Subparts B through D In order to meet the requirements of users requiring assistive technologies the following accessibility and compatibility features have been implemented in the application

bull Screen-reader-only text that allows the purpose of icons links and otherelements to be clear to non-sighted users

bull Skip navigation links

bull Tab index hierarchy on HTML elements that supports logical tab order to usersviewing the application with stylesheets disabled or without use of a mouse

bull Aria labels and titles where appropriate to make sure all forms and objects areaccessible through assistive technologies

bull High visibility contrast and color settings that conform to 508 standards aschecked with the WAVE compliance tool

bull In application help documentation that details all of the features of the applicationin plain ASCII text

bull Data tables with appropriately scoped column headers for screen readeraccessibility

Page 12 of 58

SDP Vocabulary Service

3 GETTING STARTED

This section serves as a quick reference for basic access and account configuration actions

31 ACCESSING SDP-V

The SDP-V service is accessible via a web browser by visiting the following URL httpssdp-vservicecdcgov A user account is not required to browse search and view content in the service that has been published A user account is required to author content or view content that is in draft status

Information on registering as a user is contained in Section 32 Information on accessing the content in the service via a Representational State Transfer (RESTFul) API is provided in Section 411 of this document

32 REGISTERING AS A USER

Authentication to the SDP-V service is provided via the CDC Secure Access Management Service (SAMS)4 If you receive an error message after entering your credentials into SAMS please email surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership If you do not have a SAMS account you will need to obtain one before you can register as a user with SDP-V

321 VIEWER If your only need is to view search and export published SDP-V content you may simply follow the access instructions in Section 31 to get started

322 AUTHOR In order to become an SDP-V Author users should work with their program leadership to request the ability to author content If you are uncertain who to contact contact the SDP program (see Section 7) for assistance Registering to become an SDP-V Author involves the prospective user accepting an invitation from SAMS providing information to CDC and review of this information by CDC Please allow time for your request to be reviewed and approved

323 PUBLISHER Because Publishers have the important duty of ensuring quality and encouraging harmonization they are identified when a CDC program commits to using SDP-V to author questions and response sets needed to address their data collection needs The SDP program calls this ldquoprogram onboardingrdquo Therefore SDP-V Publishers are normally designated by the associated CDC program during the program onboarding process After this onboarding process changes to Publishers can be made by sending an email request to the SDP program (see Section 7)

4 For more information about SAMS please visit httpsauthcdcgov

Page 13 of 58

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 6: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

21 SDP-V OVERVIEW

SDP-V provides a repository of Response Sets Questions Sections and SDP-V Surveys These content types are described in further detail in Section 22

Content in SDP-V can be created by Authors in the user interface or can be imported from spreadsheets that conform to the message mapping guide (MMG) or SDP-V generic template formats1 Value sets from the Public Health Information Network Vocabulary Access and Distribution System (PHIN VADS)2 are synchronized in SDP-V and can be searched reused and extended by Authors

These artifacts are accessible to SDP-V users via a graphical user interface (GUI) They are also available to other applications through an application programming interface (API)

22 TYPES OF CONTENT IN SDP-V

SDP-V serves as a repository and authoring tool for four different types of content Response Sets Questions Sections and SDP-V Surveys Figure 2 shows how the different types of content are related for better clarity the diagram can also be viewed on the SDP Vocabulary Service webpage

These content types are defined as follows

bull Response Set ndash A set of response choices that are applicable answers to one ormore questions

bull Question ndash Typically a natural language expression used to solicit a value for adata variable like ldquoWhat is your agerdquo In some cases like for defining vocabularyfor electronic information exchange this may be the data element name used tosolicit a value for the data variable instead of a natural language expression likeldquoSubjectrsquos Sexrdquo

o Response- A value that can be given as an answer to a question Commonresponse types include choice text and date3 Response type is a propertyof a question in SDP-V

bull Section ndash A grouping of questions related to a topic (eg demographic clinicallaboratory epidemiological) and intended to appear together as part of a datacollection instrument A section may also contain one or more sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquo and ldquoDiagnosisrdquo sectionswithin a ldquoClinicalrdquo section

bull SDP-V Survey ndash A SDP-V Survey defines the vocabulary (eg questions andresponse sets) used for a particular data collection or information exchange ASDP-V Survey contains one or more Sections that are combined together andintended for a data collection instrument or information exchange

1 Import of content may require coordination with the SDP-V development team See in-app help documentation for supported formats 2 PHIN VADS provides standard vocabularies particularly value sets associated with H7 message implementation guides to CDC and public

health partners More information about PHIN VADS can be found at httpswwwcdcgovphintoolsphinvadsindexhtml 3 A complete list of response types can be found at httpwwwhl7orgfhirvalueset-item-typehtml

Page 6 of 58

SDP Vocabulary Service

Figure 2 SDP-V Component Diagram

Page 7 of 58

SDP Vocabulary Service

23 SYSTEM ROLES AND CAPABILITIES SUMMARY

SDP-V has four defined user roles which allow access to specific content and capabilities These roles defined below include viewer author publisher and administrator In addition to these roles a user can belong to a collaborative authoring group See Section 24 for more information about groups Please see Appendix B Role Capabilities and Workflows for role capabilities and workflow flowcharts

231 VIEWER (PUBLIC) Anyone may browse published content in the Vocabulary service It is accessible to the public

232 AUTHOR (AUTHENTICATED USER) SDP-V Authors are identified by CDC Programs as users expected to add edit revise or curate program content To become an SDP-V Author users go through a CDC SDP-V onboarding process to obtain the needed credentials The SDP program calls this becoming an ldquoAuthenticated Userrdquo Users interested in becoming an Author should contact the SDP program (see Section 7)

2321 AUTHOR CAPABILITIES A summary of capabilities available to Authors in SDP-V is as follows bull Browse search and view details of all published contentbull Create new content (draft content until published)bull Import content (MMG or SDP-V template format)bull Browse and edit their own draft contentbull Browse and revise their own published contentbull Browse and extend published content Extending content creates a copy of

published content to use as a starting point for a userrsquos own contentExtending content creates a draft copy that includes a link to the content itwas extended from for traceability

bull Export contentbull Request draft content be published

2322 AUTHOR EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for the Author role to maximize the value of SDP-V

bull Authors are expected to reuse existing SDP-V content when possible toreduce variability and evolve toward harmonization Where reuse is notpractical Authors should document a justification to share with Publishers

bull When creating new Questions Sections and Surveys Authors are expectedto use Tags (see Section 44) whenever possible to make it easier for othersto search for and reuse content

bull Authors should verify that the Program and Surveillance System associatedwith their account in SDP-V (see Section 34) is accurate when they are

Page 8 of 58

SDP Vocabulary Service

creating new content This is to ensure that the association between SDP-V content and Programs and Surveillance Systems remains accurate This association between content and the Program and System using it helps other users of the system to better understand the context in which existing SDP-V content is used and make informed decisions to reuse content for their own data collection needs

bull Authors should include in a request for draft content to be published at leastthe followingo Whenever a Response Set or Question is extended describe why the

original content did not meet the Authorrsquos needs This context couldbe valuable to other users (eg reading level culturally preferredterm etc)

o A need date for publishing the draft content

233 PUBLISHER (AUTHENTICATED USER WITH PUBLISHER ROLE) SDP-V Publishers are identified by CDC Programs as users expected to review SDP-V survey publication requests for their program area to ensure that vocabulary is harmonized to reduce redundancy in addition to add edit revise or curate program content Publishers are authenticated SDP-V users (ie Authors) who have been granted the Publisher role In general Publishers are individuals who have expertise with surveys vocabularies public health standards and the program they support They have expertise in content needed to perform surveillance for a condition or set of conditions Publishers are responsible for SDP-V content for a single program but should have a cross-program awareness of related content to encourage cross-program harmony

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see Section 7)

A summary of capabilities available to Publishers in SDP-V are as follows

2331 PUBLISHER CAPABILTIES bull Browse and search all draft contentbull Ability to publish content that is in a draft state regardless of the author of

that contentbull All Author capabilities (See Section 2321)

2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for Publishers to maximize the value of SDP-V

bull Ensure quality of questions and response sets and ensure that Authors usepre-existing authoritative response sets (eg those synchronized from PHINVADS) where possible

bull Ensure harmony of content within the assigned programbull Encourage harmony across content for multiple programs

Page 9 of 58

SDP Vocabulary Service

bull Be responsive to Author publish requestsbull Inform Author of disposition of publish request via email

234 ADMINISTRATOR (AUTHENTICATED USER WITH ADMIN ROLE) SDP-V Administrators are identified by CDC Programs Administrators are authenticated SDP-V users (ie Authors) who have been granted the Admin role Administrators are individuals who will perform various platform tasks and maintenance on behalf of the CDC

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see section 7)

2341 ADMINSTRATOR CAPABILITIES A summary of capabilities available to Administrators in SDP-V are as follows

bull Access to an Admin Panel page (more detail in Section 6)bull Ability to curate the list of Admins Publishers Programs and Systems

currently in the systembull Ability to curate the list of groups and group membership listsbull Administrative tasks involving synchronization of elasticsearchbull All Author capabilities (See Section 2321)bull All Publisher capabilities (See Section 2331)

Page 10 of 58

SDP Vocabulary Service

24 COLLABORATIVE AUTHORING GROUPS

The current version of SDP-V allows for a user with the administrator role (see 234) to create groups of authors A group should be created if multiple authors need to view and collaborate on content that is in draft workflow status (see 25) otherwise only the original author of the content would be able to view the content prior to publication Once added to an authoring group an authenticated user can add or remove content that they have created to the group Other members of the group will subsequently have all the same abilities to edit revise and maintain that content as the original author Groups allow users to collaborate with other authors while creating and revising content On a userrsquos account details page (to display account details click the userrsquos email in the top right then select ldquosettings)rdquo the user can see a list of all groups where an administrator has granted access

25 KEY TERMS

bull Tag ndash A keyword from a controlled vocabulary applied to a question section orsurvey to help facilitate finding relevant questions during a search

bull Workflow Status ndash SDP-V content can be in either a Draft or Published workflowstatus

o Draft ndash When content is created in SDP-V it is in Draft status

Visibility Content in draft workflow status is only visible to the user whoauthored it users that belong to a group that the content is added to(see section 24) and to all Publishers in the system

Ability to Modify Content Only the Author or group members maymake changes to the draft content The draft content can be edited asdesired until it is ready to be sent to a Publisher for review SDP-V trackschanges to draft content

Page 11 of 58

SDP Vocabulary Service

o Published ndash Content must be reviewed and approved by a Publisher (seeSection 233 in SDP-V to move into Published workflow status

Visibility Published content is visible to everyone who has access toSDP-V

Ability to Modify Content Only the Author or group members ofPublished content may choose to revise it This creates a new version ofthe content in draft status SDP-V maintains a version history for contentso that users can see how content has evolved over time

Note Published content is not necessarily authoritative andcontributions from external (ie outside CDC) partners should becoordinated by associated CDC programs Published content indicatesthat a program was ready to share content with others to promotetransparency harmonization standardization and the goals of SDP-VSDP-V is developing features that will be available in future release thatwill help users curate content and help programs identify preferredquestions and response sets to use in future data collection instruments

26 OPERATIONAL STATUS

The current version of SDP-V is the first major production release representing a minimally viable set of features Future releases will incorporate additional capability development based on feedback and feature requests from existing and future users

27 SECTION 508 COMPLIANCE AND ACCESIBILITY FEATURES

The current version of SDP-V has been tested according to HHS Section 508 Subparts B through D In order to meet the requirements of users requiring assistive technologies the following accessibility and compatibility features have been implemented in the application

bull Screen-reader-only text that allows the purpose of icons links and otherelements to be clear to non-sighted users

bull Skip navigation links

bull Tab index hierarchy on HTML elements that supports logical tab order to usersviewing the application with stylesheets disabled or without use of a mouse

bull Aria labels and titles where appropriate to make sure all forms and objects areaccessible through assistive technologies

bull High visibility contrast and color settings that conform to 508 standards aschecked with the WAVE compliance tool

bull In application help documentation that details all of the features of the applicationin plain ASCII text

bull Data tables with appropriately scoped column headers for screen readeraccessibility

Page 12 of 58

SDP Vocabulary Service

3 GETTING STARTED

This section serves as a quick reference for basic access and account configuration actions

31 ACCESSING SDP-V

The SDP-V service is accessible via a web browser by visiting the following URL httpssdp-vservicecdcgov A user account is not required to browse search and view content in the service that has been published A user account is required to author content or view content that is in draft status

Information on registering as a user is contained in Section 32 Information on accessing the content in the service via a Representational State Transfer (RESTFul) API is provided in Section 411 of this document

32 REGISTERING AS A USER

Authentication to the SDP-V service is provided via the CDC Secure Access Management Service (SAMS)4 If you receive an error message after entering your credentials into SAMS please email surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership If you do not have a SAMS account you will need to obtain one before you can register as a user with SDP-V

321 VIEWER If your only need is to view search and export published SDP-V content you may simply follow the access instructions in Section 31 to get started

322 AUTHOR In order to become an SDP-V Author users should work with their program leadership to request the ability to author content If you are uncertain who to contact contact the SDP program (see Section 7) for assistance Registering to become an SDP-V Author involves the prospective user accepting an invitation from SAMS providing information to CDC and review of this information by CDC Please allow time for your request to be reviewed and approved

323 PUBLISHER Because Publishers have the important duty of ensuring quality and encouraging harmonization they are identified when a CDC program commits to using SDP-V to author questions and response sets needed to address their data collection needs The SDP program calls this ldquoprogram onboardingrdquo Therefore SDP-V Publishers are normally designated by the associated CDC program during the program onboarding process After this onboarding process changes to Publishers can be made by sending an email request to the SDP program (see Section 7)

4 For more information about SAMS please visit httpsauthcdcgov

Page 13 of 58

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 7: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

Figure 2 SDP-V Component Diagram

Page 7 of 58

SDP Vocabulary Service

23 SYSTEM ROLES AND CAPABILITIES SUMMARY

SDP-V has four defined user roles which allow access to specific content and capabilities These roles defined below include viewer author publisher and administrator In addition to these roles a user can belong to a collaborative authoring group See Section 24 for more information about groups Please see Appendix B Role Capabilities and Workflows for role capabilities and workflow flowcharts

231 VIEWER (PUBLIC) Anyone may browse published content in the Vocabulary service It is accessible to the public

232 AUTHOR (AUTHENTICATED USER) SDP-V Authors are identified by CDC Programs as users expected to add edit revise or curate program content To become an SDP-V Author users go through a CDC SDP-V onboarding process to obtain the needed credentials The SDP program calls this becoming an ldquoAuthenticated Userrdquo Users interested in becoming an Author should contact the SDP program (see Section 7)

2321 AUTHOR CAPABILITIES A summary of capabilities available to Authors in SDP-V is as follows bull Browse search and view details of all published contentbull Create new content (draft content until published)bull Import content (MMG or SDP-V template format)bull Browse and edit their own draft contentbull Browse and revise their own published contentbull Browse and extend published content Extending content creates a copy of

published content to use as a starting point for a userrsquos own contentExtending content creates a draft copy that includes a link to the content itwas extended from for traceability

bull Export contentbull Request draft content be published

2322 AUTHOR EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for the Author role to maximize the value of SDP-V

bull Authors are expected to reuse existing SDP-V content when possible toreduce variability and evolve toward harmonization Where reuse is notpractical Authors should document a justification to share with Publishers

bull When creating new Questions Sections and Surveys Authors are expectedto use Tags (see Section 44) whenever possible to make it easier for othersto search for and reuse content

bull Authors should verify that the Program and Surveillance System associatedwith their account in SDP-V (see Section 34) is accurate when they are

Page 8 of 58

SDP Vocabulary Service

creating new content This is to ensure that the association between SDP-V content and Programs and Surveillance Systems remains accurate This association between content and the Program and System using it helps other users of the system to better understand the context in which existing SDP-V content is used and make informed decisions to reuse content for their own data collection needs

bull Authors should include in a request for draft content to be published at leastthe followingo Whenever a Response Set or Question is extended describe why the

original content did not meet the Authorrsquos needs This context couldbe valuable to other users (eg reading level culturally preferredterm etc)

o A need date for publishing the draft content

233 PUBLISHER (AUTHENTICATED USER WITH PUBLISHER ROLE) SDP-V Publishers are identified by CDC Programs as users expected to review SDP-V survey publication requests for their program area to ensure that vocabulary is harmonized to reduce redundancy in addition to add edit revise or curate program content Publishers are authenticated SDP-V users (ie Authors) who have been granted the Publisher role In general Publishers are individuals who have expertise with surveys vocabularies public health standards and the program they support They have expertise in content needed to perform surveillance for a condition or set of conditions Publishers are responsible for SDP-V content for a single program but should have a cross-program awareness of related content to encourage cross-program harmony

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see Section 7)

A summary of capabilities available to Publishers in SDP-V are as follows

2331 PUBLISHER CAPABILTIES bull Browse and search all draft contentbull Ability to publish content that is in a draft state regardless of the author of

that contentbull All Author capabilities (See Section 2321)

2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for Publishers to maximize the value of SDP-V

bull Ensure quality of questions and response sets and ensure that Authors usepre-existing authoritative response sets (eg those synchronized from PHINVADS) where possible

bull Ensure harmony of content within the assigned programbull Encourage harmony across content for multiple programs

Page 9 of 58

SDP Vocabulary Service

bull Be responsive to Author publish requestsbull Inform Author of disposition of publish request via email

234 ADMINISTRATOR (AUTHENTICATED USER WITH ADMIN ROLE) SDP-V Administrators are identified by CDC Programs Administrators are authenticated SDP-V users (ie Authors) who have been granted the Admin role Administrators are individuals who will perform various platform tasks and maintenance on behalf of the CDC

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see section 7)

2341 ADMINSTRATOR CAPABILITIES A summary of capabilities available to Administrators in SDP-V are as follows

bull Access to an Admin Panel page (more detail in Section 6)bull Ability to curate the list of Admins Publishers Programs and Systems

currently in the systembull Ability to curate the list of groups and group membership listsbull Administrative tasks involving synchronization of elasticsearchbull All Author capabilities (See Section 2321)bull All Publisher capabilities (See Section 2331)

Page 10 of 58

SDP Vocabulary Service

24 COLLABORATIVE AUTHORING GROUPS

The current version of SDP-V allows for a user with the administrator role (see 234) to create groups of authors A group should be created if multiple authors need to view and collaborate on content that is in draft workflow status (see 25) otherwise only the original author of the content would be able to view the content prior to publication Once added to an authoring group an authenticated user can add or remove content that they have created to the group Other members of the group will subsequently have all the same abilities to edit revise and maintain that content as the original author Groups allow users to collaborate with other authors while creating and revising content On a userrsquos account details page (to display account details click the userrsquos email in the top right then select ldquosettings)rdquo the user can see a list of all groups where an administrator has granted access

25 KEY TERMS

bull Tag ndash A keyword from a controlled vocabulary applied to a question section orsurvey to help facilitate finding relevant questions during a search

bull Workflow Status ndash SDP-V content can be in either a Draft or Published workflowstatus

o Draft ndash When content is created in SDP-V it is in Draft status

Visibility Content in draft workflow status is only visible to the user whoauthored it users that belong to a group that the content is added to(see section 24) and to all Publishers in the system

Ability to Modify Content Only the Author or group members maymake changes to the draft content The draft content can be edited asdesired until it is ready to be sent to a Publisher for review SDP-V trackschanges to draft content

Page 11 of 58

SDP Vocabulary Service

o Published ndash Content must be reviewed and approved by a Publisher (seeSection 233 in SDP-V to move into Published workflow status

Visibility Published content is visible to everyone who has access toSDP-V

Ability to Modify Content Only the Author or group members ofPublished content may choose to revise it This creates a new version ofthe content in draft status SDP-V maintains a version history for contentso that users can see how content has evolved over time

Note Published content is not necessarily authoritative andcontributions from external (ie outside CDC) partners should becoordinated by associated CDC programs Published content indicatesthat a program was ready to share content with others to promotetransparency harmonization standardization and the goals of SDP-VSDP-V is developing features that will be available in future release thatwill help users curate content and help programs identify preferredquestions and response sets to use in future data collection instruments

26 OPERATIONAL STATUS

The current version of SDP-V is the first major production release representing a minimally viable set of features Future releases will incorporate additional capability development based on feedback and feature requests from existing and future users

27 SECTION 508 COMPLIANCE AND ACCESIBILITY FEATURES

The current version of SDP-V has been tested according to HHS Section 508 Subparts B through D In order to meet the requirements of users requiring assistive technologies the following accessibility and compatibility features have been implemented in the application

bull Screen-reader-only text that allows the purpose of icons links and otherelements to be clear to non-sighted users

bull Skip navigation links

bull Tab index hierarchy on HTML elements that supports logical tab order to usersviewing the application with stylesheets disabled or without use of a mouse

bull Aria labels and titles where appropriate to make sure all forms and objects areaccessible through assistive technologies

bull High visibility contrast and color settings that conform to 508 standards aschecked with the WAVE compliance tool

bull In application help documentation that details all of the features of the applicationin plain ASCII text

bull Data tables with appropriately scoped column headers for screen readeraccessibility

Page 12 of 58

SDP Vocabulary Service

3 GETTING STARTED

This section serves as a quick reference for basic access and account configuration actions

31 ACCESSING SDP-V

The SDP-V service is accessible via a web browser by visiting the following URL httpssdp-vservicecdcgov A user account is not required to browse search and view content in the service that has been published A user account is required to author content or view content that is in draft status

Information on registering as a user is contained in Section 32 Information on accessing the content in the service via a Representational State Transfer (RESTFul) API is provided in Section 411 of this document

32 REGISTERING AS A USER

Authentication to the SDP-V service is provided via the CDC Secure Access Management Service (SAMS)4 If you receive an error message after entering your credentials into SAMS please email surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership If you do not have a SAMS account you will need to obtain one before you can register as a user with SDP-V

321 VIEWER If your only need is to view search and export published SDP-V content you may simply follow the access instructions in Section 31 to get started

322 AUTHOR In order to become an SDP-V Author users should work with their program leadership to request the ability to author content If you are uncertain who to contact contact the SDP program (see Section 7) for assistance Registering to become an SDP-V Author involves the prospective user accepting an invitation from SAMS providing information to CDC and review of this information by CDC Please allow time for your request to be reviewed and approved

323 PUBLISHER Because Publishers have the important duty of ensuring quality and encouraging harmonization they are identified when a CDC program commits to using SDP-V to author questions and response sets needed to address their data collection needs The SDP program calls this ldquoprogram onboardingrdquo Therefore SDP-V Publishers are normally designated by the associated CDC program during the program onboarding process After this onboarding process changes to Publishers can be made by sending an email request to the SDP program (see Section 7)

4 For more information about SAMS please visit httpsauthcdcgov

Page 13 of 58

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 8: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

23 SYSTEM ROLES AND CAPABILITIES SUMMARY

SDP-V has four defined user roles which allow access to specific content and capabilities These roles defined below include viewer author publisher and administrator In addition to these roles a user can belong to a collaborative authoring group See Section 24 for more information about groups Please see Appendix B Role Capabilities and Workflows for role capabilities and workflow flowcharts

231 VIEWER (PUBLIC) Anyone may browse published content in the Vocabulary service It is accessible to the public

232 AUTHOR (AUTHENTICATED USER) SDP-V Authors are identified by CDC Programs as users expected to add edit revise or curate program content To become an SDP-V Author users go through a CDC SDP-V onboarding process to obtain the needed credentials The SDP program calls this becoming an ldquoAuthenticated Userrdquo Users interested in becoming an Author should contact the SDP program (see Section 7)

2321 AUTHOR CAPABILITIES A summary of capabilities available to Authors in SDP-V is as follows bull Browse search and view details of all published contentbull Create new content (draft content until published)bull Import content (MMG or SDP-V template format)bull Browse and edit their own draft contentbull Browse and revise their own published contentbull Browse and extend published content Extending content creates a copy of

published content to use as a starting point for a userrsquos own contentExtending content creates a draft copy that includes a link to the content itwas extended from for traceability

bull Export contentbull Request draft content be published

2322 AUTHOR EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for the Author role to maximize the value of SDP-V

bull Authors are expected to reuse existing SDP-V content when possible toreduce variability and evolve toward harmonization Where reuse is notpractical Authors should document a justification to share with Publishers

bull When creating new Questions Sections and Surveys Authors are expectedto use Tags (see Section 44) whenever possible to make it easier for othersto search for and reuse content

bull Authors should verify that the Program and Surveillance System associatedwith their account in SDP-V (see Section 34) is accurate when they are

Page 8 of 58

SDP Vocabulary Service

creating new content This is to ensure that the association between SDP-V content and Programs and Surveillance Systems remains accurate This association between content and the Program and System using it helps other users of the system to better understand the context in which existing SDP-V content is used and make informed decisions to reuse content for their own data collection needs

bull Authors should include in a request for draft content to be published at leastthe followingo Whenever a Response Set or Question is extended describe why the

original content did not meet the Authorrsquos needs This context couldbe valuable to other users (eg reading level culturally preferredterm etc)

o A need date for publishing the draft content

233 PUBLISHER (AUTHENTICATED USER WITH PUBLISHER ROLE) SDP-V Publishers are identified by CDC Programs as users expected to review SDP-V survey publication requests for their program area to ensure that vocabulary is harmonized to reduce redundancy in addition to add edit revise or curate program content Publishers are authenticated SDP-V users (ie Authors) who have been granted the Publisher role In general Publishers are individuals who have expertise with surveys vocabularies public health standards and the program they support They have expertise in content needed to perform surveillance for a condition or set of conditions Publishers are responsible for SDP-V content for a single program but should have a cross-program awareness of related content to encourage cross-program harmony

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see Section 7)

A summary of capabilities available to Publishers in SDP-V are as follows

2331 PUBLISHER CAPABILTIES bull Browse and search all draft contentbull Ability to publish content that is in a draft state regardless of the author of

that contentbull All Author capabilities (See Section 2321)

2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for Publishers to maximize the value of SDP-V

bull Ensure quality of questions and response sets and ensure that Authors usepre-existing authoritative response sets (eg those synchronized from PHINVADS) where possible

bull Ensure harmony of content within the assigned programbull Encourage harmony across content for multiple programs

Page 9 of 58

SDP Vocabulary Service

bull Be responsive to Author publish requestsbull Inform Author of disposition of publish request via email

234 ADMINISTRATOR (AUTHENTICATED USER WITH ADMIN ROLE) SDP-V Administrators are identified by CDC Programs Administrators are authenticated SDP-V users (ie Authors) who have been granted the Admin role Administrators are individuals who will perform various platform tasks and maintenance on behalf of the CDC

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see section 7)

2341 ADMINSTRATOR CAPABILITIES A summary of capabilities available to Administrators in SDP-V are as follows

bull Access to an Admin Panel page (more detail in Section 6)bull Ability to curate the list of Admins Publishers Programs and Systems

currently in the systembull Ability to curate the list of groups and group membership listsbull Administrative tasks involving synchronization of elasticsearchbull All Author capabilities (See Section 2321)bull All Publisher capabilities (See Section 2331)

Page 10 of 58

SDP Vocabulary Service

24 COLLABORATIVE AUTHORING GROUPS

The current version of SDP-V allows for a user with the administrator role (see 234) to create groups of authors A group should be created if multiple authors need to view and collaborate on content that is in draft workflow status (see 25) otherwise only the original author of the content would be able to view the content prior to publication Once added to an authoring group an authenticated user can add or remove content that they have created to the group Other members of the group will subsequently have all the same abilities to edit revise and maintain that content as the original author Groups allow users to collaborate with other authors while creating and revising content On a userrsquos account details page (to display account details click the userrsquos email in the top right then select ldquosettings)rdquo the user can see a list of all groups where an administrator has granted access

25 KEY TERMS

bull Tag ndash A keyword from a controlled vocabulary applied to a question section orsurvey to help facilitate finding relevant questions during a search

bull Workflow Status ndash SDP-V content can be in either a Draft or Published workflowstatus

o Draft ndash When content is created in SDP-V it is in Draft status

Visibility Content in draft workflow status is only visible to the user whoauthored it users that belong to a group that the content is added to(see section 24) and to all Publishers in the system

Ability to Modify Content Only the Author or group members maymake changes to the draft content The draft content can be edited asdesired until it is ready to be sent to a Publisher for review SDP-V trackschanges to draft content

Page 11 of 58

SDP Vocabulary Service

o Published ndash Content must be reviewed and approved by a Publisher (seeSection 233 in SDP-V to move into Published workflow status

Visibility Published content is visible to everyone who has access toSDP-V

Ability to Modify Content Only the Author or group members ofPublished content may choose to revise it This creates a new version ofthe content in draft status SDP-V maintains a version history for contentso that users can see how content has evolved over time

Note Published content is not necessarily authoritative andcontributions from external (ie outside CDC) partners should becoordinated by associated CDC programs Published content indicatesthat a program was ready to share content with others to promotetransparency harmonization standardization and the goals of SDP-VSDP-V is developing features that will be available in future release thatwill help users curate content and help programs identify preferredquestions and response sets to use in future data collection instruments

26 OPERATIONAL STATUS

The current version of SDP-V is the first major production release representing a minimally viable set of features Future releases will incorporate additional capability development based on feedback and feature requests from existing and future users

27 SECTION 508 COMPLIANCE AND ACCESIBILITY FEATURES

The current version of SDP-V has been tested according to HHS Section 508 Subparts B through D In order to meet the requirements of users requiring assistive technologies the following accessibility and compatibility features have been implemented in the application

bull Screen-reader-only text that allows the purpose of icons links and otherelements to be clear to non-sighted users

bull Skip navigation links

bull Tab index hierarchy on HTML elements that supports logical tab order to usersviewing the application with stylesheets disabled or without use of a mouse

bull Aria labels and titles where appropriate to make sure all forms and objects areaccessible through assistive technologies

bull High visibility contrast and color settings that conform to 508 standards aschecked with the WAVE compliance tool

bull In application help documentation that details all of the features of the applicationin plain ASCII text

bull Data tables with appropriately scoped column headers for screen readeraccessibility

Page 12 of 58

SDP Vocabulary Service

3 GETTING STARTED

This section serves as a quick reference for basic access and account configuration actions

31 ACCESSING SDP-V

The SDP-V service is accessible via a web browser by visiting the following URL httpssdp-vservicecdcgov A user account is not required to browse search and view content in the service that has been published A user account is required to author content or view content that is in draft status

Information on registering as a user is contained in Section 32 Information on accessing the content in the service via a Representational State Transfer (RESTFul) API is provided in Section 411 of this document

32 REGISTERING AS A USER

Authentication to the SDP-V service is provided via the CDC Secure Access Management Service (SAMS)4 If you receive an error message after entering your credentials into SAMS please email surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership If you do not have a SAMS account you will need to obtain one before you can register as a user with SDP-V

321 VIEWER If your only need is to view search and export published SDP-V content you may simply follow the access instructions in Section 31 to get started

322 AUTHOR In order to become an SDP-V Author users should work with their program leadership to request the ability to author content If you are uncertain who to contact contact the SDP program (see Section 7) for assistance Registering to become an SDP-V Author involves the prospective user accepting an invitation from SAMS providing information to CDC and review of this information by CDC Please allow time for your request to be reviewed and approved

323 PUBLISHER Because Publishers have the important duty of ensuring quality and encouraging harmonization they are identified when a CDC program commits to using SDP-V to author questions and response sets needed to address their data collection needs The SDP program calls this ldquoprogram onboardingrdquo Therefore SDP-V Publishers are normally designated by the associated CDC program during the program onboarding process After this onboarding process changes to Publishers can be made by sending an email request to the SDP program (see Section 7)

4 For more information about SAMS please visit httpsauthcdcgov

Page 13 of 58

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 9: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

creating new content This is to ensure that the association between SDP-V content and Programs and Surveillance Systems remains accurate This association between content and the Program and System using it helps other users of the system to better understand the context in which existing SDP-V content is used and make informed decisions to reuse content for their own data collection needs

bull Authors should include in a request for draft content to be published at leastthe followingo Whenever a Response Set or Question is extended describe why the

original content did not meet the Authorrsquos needs This context couldbe valuable to other users (eg reading level culturally preferredterm etc)

o A need date for publishing the draft content

233 PUBLISHER (AUTHENTICATED USER WITH PUBLISHER ROLE) SDP-V Publishers are identified by CDC Programs as users expected to review SDP-V survey publication requests for their program area to ensure that vocabulary is harmonized to reduce redundancy in addition to add edit revise or curate program content Publishers are authenticated SDP-V users (ie Authors) who have been granted the Publisher role In general Publishers are individuals who have expertise with surveys vocabularies public health standards and the program they support They have expertise in content needed to perform surveillance for a condition or set of conditions Publishers are responsible for SDP-V content for a single program but should have a cross-program awareness of related content to encourage cross-program harmony

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see Section 7)

A summary of capabilities available to Publishers in SDP-V are as follows

2331 PUBLISHER CAPABILTIES bull Browse and search all draft contentbull Ability to publish content that is in a draft state regardless of the author of

that contentbull All Author capabilities (See Section 2321)

2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES There are several expectations and best practices for Publishers to maximize the value of SDP-V

bull Ensure quality of questions and response sets and ensure that Authors usepre-existing authoritative response sets (eg those synchronized from PHINVADS) where possible

bull Ensure harmony of content within the assigned programbull Encourage harmony across content for multiple programs

Page 9 of 58

SDP Vocabulary Service

bull Be responsive to Author publish requestsbull Inform Author of disposition of publish request via email

234 ADMINISTRATOR (AUTHENTICATED USER WITH ADMIN ROLE) SDP-V Administrators are identified by CDC Programs Administrators are authenticated SDP-V users (ie Authors) who have been granted the Admin role Administrators are individuals who will perform various platform tasks and maintenance on behalf of the CDC

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see section 7)

2341 ADMINSTRATOR CAPABILITIES A summary of capabilities available to Administrators in SDP-V are as follows

bull Access to an Admin Panel page (more detail in Section 6)bull Ability to curate the list of Admins Publishers Programs and Systems

currently in the systembull Ability to curate the list of groups and group membership listsbull Administrative tasks involving synchronization of elasticsearchbull All Author capabilities (See Section 2321)bull All Publisher capabilities (See Section 2331)

Page 10 of 58

SDP Vocabulary Service

24 COLLABORATIVE AUTHORING GROUPS

The current version of SDP-V allows for a user with the administrator role (see 234) to create groups of authors A group should be created if multiple authors need to view and collaborate on content that is in draft workflow status (see 25) otherwise only the original author of the content would be able to view the content prior to publication Once added to an authoring group an authenticated user can add or remove content that they have created to the group Other members of the group will subsequently have all the same abilities to edit revise and maintain that content as the original author Groups allow users to collaborate with other authors while creating and revising content On a userrsquos account details page (to display account details click the userrsquos email in the top right then select ldquosettings)rdquo the user can see a list of all groups where an administrator has granted access

25 KEY TERMS

bull Tag ndash A keyword from a controlled vocabulary applied to a question section orsurvey to help facilitate finding relevant questions during a search

bull Workflow Status ndash SDP-V content can be in either a Draft or Published workflowstatus

o Draft ndash When content is created in SDP-V it is in Draft status

Visibility Content in draft workflow status is only visible to the user whoauthored it users that belong to a group that the content is added to(see section 24) and to all Publishers in the system

Ability to Modify Content Only the Author or group members maymake changes to the draft content The draft content can be edited asdesired until it is ready to be sent to a Publisher for review SDP-V trackschanges to draft content

Page 11 of 58

SDP Vocabulary Service

o Published ndash Content must be reviewed and approved by a Publisher (seeSection 233 in SDP-V to move into Published workflow status

Visibility Published content is visible to everyone who has access toSDP-V

Ability to Modify Content Only the Author or group members ofPublished content may choose to revise it This creates a new version ofthe content in draft status SDP-V maintains a version history for contentso that users can see how content has evolved over time

Note Published content is not necessarily authoritative andcontributions from external (ie outside CDC) partners should becoordinated by associated CDC programs Published content indicatesthat a program was ready to share content with others to promotetransparency harmonization standardization and the goals of SDP-VSDP-V is developing features that will be available in future release thatwill help users curate content and help programs identify preferredquestions and response sets to use in future data collection instruments

26 OPERATIONAL STATUS

The current version of SDP-V is the first major production release representing a minimally viable set of features Future releases will incorporate additional capability development based on feedback and feature requests from existing and future users

27 SECTION 508 COMPLIANCE AND ACCESIBILITY FEATURES

The current version of SDP-V has been tested according to HHS Section 508 Subparts B through D In order to meet the requirements of users requiring assistive technologies the following accessibility and compatibility features have been implemented in the application

bull Screen-reader-only text that allows the purpose of icons links and otherelements to be clear to non-sighted users

bull Skip navigation links

bull Tab index hierarchy on HTML elements that supports logical tab order to usersviewing the application with stylesheets disabled or without use of a mouse

bull Aria labels and titles where appropriate to make sure all forms and objects areaccessible through assistive technologies

bull High visibility contrast and color settings that conform to 508 standards aschecked with the WAVE compliance tool

bull In application help documentation that details all of the features of the applicationin plain ASCII text

bull Data tables with appropriately scoped column headers for screen readeraccessibility

Page 12 of 58

SDP Vocabulary Service

3 GETTING STARTED

This section serves as a quick reference for basic access and account configuration actions

31 ACCESSING SDP-V

The SDP-V service is accessible via a web browser by visiting the following URL httpssdp-vservicecdcgov A user account is not required to browse search and view content in the service that has been published A user account is required to author content or view content that is in draft status

Information on registering as a user is contained in Section 32 Information on accessing the content in the service via a Representational State Transfer (RESTFul) API is provided in Section 411 of this document

32 REGISTERING AS A USER

Authentication to the SDP-V service is provided via the CDC Secure Access Management Service (SAMS)4 If you receive an error message after entering your credentials into SAMS please email surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership If you do not have a SAMS account you will need to obtain one before you can register as a user with SDP-V

321 VIEWER If your only need is to view search and export published SDP-V content you may simply follow the access instructions in Section 31 to get started

322 AUTHOR In order to become an SDP-V Author users should work with their program leadership to request the ability to author content If you are uncertain who to contact contact the SDP program (see Section 7) for assistance Registering to become an SDP-V Author involves the prospective user accepting an invitation from SAMS providing information to CDC and review of this information by CDC Please allow time for your request to be reviewed and approved

323 PUBLISHER Because Publishers have the important duty of ensuring quality and encouraging harmonization they are identified when a CDC program commits to using SDP-V to author questions and response sets needed to address their data collection needs The SDP program calls this ldquoprogram onboardingrdquo Therefore SDP-V Publishers are normally designated by the associated CDC program during the program onboarding process After this onboarding process changes to Publishers can be made by sending an email request to the SDP program (see Section 7)

4 For more information about SAMS please visit httpsauthcdcgov

Page 13 of 58

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 10: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

bull Be responsive to Author publish requestsbull Inform Author of disposition of publish request via email

234 ADMINISTRATOR (AUTHENTICATED USER WITH ADMIN ROLE) SDP-V Administrators are identified by CDC Programs Administrators are authenticated SDP-V users (ie Authors) who have been granted the Admin role Administrators are individuals who will perform various platform tasks and maintenance on behalf of the CDC

SDP-V Authors who are interested in becoming Publishers should either contact the appropriate CDC program with this request or should contact the SDP program for further assistance (see section 7)

2341 ADMINSTRATOR CAPABILITIES A summary of capabilities available to Administrators in SDP-V are as follows

bull Access to an Admin Panel page (more detail in Section 6)bull Ability to curate the list of Admins Publishers Programs and Systems

currently in the systembull Ability to curate the list of groups and group membership listsbull Administrative tasks involving synchronization of elasticsearchbull All Author capabilities (See Section 2321)bull All Publisher capabilities (See Section 2331)

Page 10 of 58

SDP Vocabulary Service

24 COLLABORATIVE AUTHORING GROUPS

The current version of SDP-V allows for a user with the administrator role (see 234) to create groups of authors A group should be created if multiple authors need to view and collaborate on content that is in draft workflow status (see 25) otherwise only the original author of the content would be able to view the content prior to publication Once added to an authoring group an authenticated user can add or remove content that they have created to the group Other members of the group will subsequently have all the same abilities to edit revise and maintain that content as the original author Groups allow users to collaborate with other authors while creating and revising content On a userrsquos account details page (to display account details click the userrsquos email in the top right then select ldquosettings)rdquo the user can see a list of all groups where an administrator has granted access

25 KEY TERMS

bull Tag ndash A keyword from a controlled vocabulary applied to a question section orsurvey to help facilitate finding relevant questions during a search

bull Workflow Status ndash SDP-V content can be in either a Draft or Published workflowstatus

o Draft ndash When content is created in SDP-V it is in Draft status

Visibility Content in draft workflow status is only visible to the user whoauthored it users that belong to a group that the content is added to(see section 24) and to all Publishers in the system

Ability to Modify Content Only the Author or group members maymake changes to the draft content The draft content can be edited asdesired until it is ready to be sent to a Publisher for review SDP-V trackschanges to draft content

Page 11 of 58

SDP Vocabulary Service

o Published ndash Content must be reviewed and approved by a Publisher (seeSection 233 in SDP-V to move into Published workflow status

Visibility Published content is visible to everyone who has access toSDP-V

Ability to Modify Content Only the Author or group members ofPublished content may choose to revise it This creates a new version ofthe content in draft status SDP-V maintains a version history for contentso that users can see how content has evolved over time

Note Published content is not necessarily authoritative andcontributions from external (ie outside CDC) partners should becoordinated by associated CDC programs Published content indicatesthat a program was ready to share content with others to promotetransparency harmonization standardization and the goals of SDP-VSDP-V is developing features that will be available in future release thatwill help users curate content and help programs identify preferredquestions and response sets to use in future data collection instruments

26 OPERATIONAL STATUS

The current version of SDP-V is the first major production release representing a minimally viable set of features Future releases will incorporate additional capability development based on feedback and feature requests from existing and future users

27 SECTION 508 COMPLIANCE AND ACCESIBILITY FEATURES

The current version of SDP-V has been tested according to HHS Section 508 Subparts B through D In order to meet the requirements of users requiring assistive technologies the following accessibility and compatibility features have been implemented in the application

bull Screen-reader-only text that allows the purpose of icons links and otherelements to be clear to non-sighted users

bull Skip navigation links

bull Tab index hierarchy on HTML elements that supports logical tab order to usersviewing the application with stylesheets disabled or without use of a mouse

bull Aria labels and titles where appropriate to make sure all forms and objects areaccessible through assistive technologies

bull High visibility contrast and color settings that conform to 508 standards aschecked with the WAVE compliance tool

bull In application help documentation that details all of the features of the applicationin plain ASCII text

bull Data tables with appropriately scoped column headers for screen readeraccessibility

Page 12 of 58

SDP Vocabulary Service

3 GETTING STARTED

This section serves as a quick reference for basic access and account configuration actions

31 ACCESSING SDP-V

The SDP-V service is accessible via a web browser by visiting the following URL httpssdp-vservicecdcgov A user account is not required to browse search and view content in the service that has been published A user account is required to author content or view content that is in draft status

Information on registering as a user is contained in Section 32 Information on accessing the content in the service via a Representational State Transfer (RESTFul) API is provided in Section 411 of this document

32 REGISTERING AS A USER

Authentication to the SDP-V service is provided via the CDC Secure Access Management Service (SAMS)4 If you receive an error message after entering your credentials into SAMS please email surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership If you do not have a SAMS account you will need to obtain one before you can register as a user with SDP-V

321 VIEWER If your only need is to view search and export published SDP-V content you may simply follow the access instructions in Section 31 to get started

322 AUTHOR In order to become an SDP-V Author users should work with their program leadership to request the ability to author content If you are uncertain who to contact contact the SDP program (see Section 7) for assistance Registering to become an SDP-V Author involves the prospective user accepting an invitation from SAMS providing information to CDC and review of this information by CDC Please allow time for your request to be reviewed and approved

323 PUBLISHER Because Publishers have the important duty of ensuring quality and encouraging harmonization they are identified when a CDC program commits to using SDP-V to author questions and response sets needed to address their data collection needs The SDP program calls this ldquoprogram onboardingrdquo Therefore SDP-V Publishers are normally designated by the associated CDC program during the program onboarding process After this onboarding process changes to Publishers can be made by sending an email request to the SDP program (see Section 7)

4 For more information about SAMS please visit httpsauthcdcgov

Page 13 of 58

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 11: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

24 COLLABORATIVE AUTHORING GROUPS

The current version of SDP-V allows for a user with the administrator role (see 234) to create groups of authors A group should be created if multiple authors need to view and collaborate on content that is in draft workflow status (see 25) otherwise only the original author of the content would be able to view the content prior to publication Once added to an authoring group an authenticated user can add or remove content that they have created to the group Other members of the group will subsequently have all the same abilities to edit revise and maintain that content as the original author Groups allow users to collaborate with other authors while creating and revising content On a userrsquos account details page (to display account details click the userrsquos email in the top right then select ldquosettings)rdquo the user can see a list of all groups where an administrator has granted access

25 KEY TERMS

bull Tag ndash A keyword from a controlled vocabulary applied to a question section orsurvey to help facilitate finding relevant questions during a search

bull Workflow Status ndash SDP-V content can be in either a Draft or Published workflowstatus

o Draft ndash When content is created in SDP-V it is in Draft status

Visibility Content in draft workflow status is only visible to the user whoauthored it users that belong to a group that the content is added to(see section 24) and to all Publishers in the system

Ability to Modify Content Only the Author or group members maymake changes to the draft content The draft content can be edited asdesired until it is ready to be sent to a Publisher for review SDP-V trackschanges to draft content

Page 11 of 58

SDP Vocabulary Service

o Published ndash Content must be reviewed and approved by a Publisher (seeSection 233 in SDP-V to move into Published workflow status

Visibility Published content is visible to everyone who has access toSDP-V

Ability to Modify Content Only the Author or group members ofPublished content may choose to revise it This creates a new version ofthe content in draft status SDP-V maintains a version history for contentso that users can see how content has evolved over time

Note Published content is not necessarily authoritative andcontributions from external (ie outside CDC) partners should becoordinated by associated CDC programs Published content indicatesthat a program was ready to share content with others to promotetransparency harmonization standardization and the goals of SDP-VSDP-V is developing features that will be available in future release thatwill help users curate content and help programs identify preferredquestions and response sets to use in future data collection instruments

26 OPERATIONAL STATUS

The current version of SDP-V is the first major production release representing a minimally viable set of features Future releases will incorporate additional capability development based on feedback and feature requests from existing and future users

27 SECTION 508 COMPLIANCE AND ACCESIBILITY FEATURES

The current version of SDP-V has been tested according to HHS Section 508 Subparts B through D In order to meet the requirements of users requiring assistive technologies the following accessibility and compatibility features have been implemented in the application

bull Screen-reader-only text that allows the purpose of icons links and otherelements to be clear to non-sighted users

bull Skip navigation links

bull Tab index hierarchy on HTML elements that supports logical tab order to usersviewing the application with stylesheets disabled or without use of a mouse

bull Aria labels and titles where appropriate to make sure all forms and objects areaccessible through assistive technologies

bull High visibility contrast and color settings that conform to 508 standards aschecked with the WAVE compliance tool

bull In application help documentation that details all of the features of the applicationin plain ASCII text

bull Data tables with appropriately scoped column headers for screen readeraccessibility

Page 12 of 58

SDP Vocabulary Service

3 GETTING STARTED

This section serves as a quick reference for basic access and account configuration actions

31 ACCESSING SDP-V

The SDP-V service is accessible via a web browser by visiting the following URL httpssdp-vservicecdcgov A user account is not required to browse search and view content in the service that has been published A user account is required to author content or view content that is in draft status

Information on registering as a user is contained in Section 32 Information on accessing the content in the service via a Representational State Transfer (RESTFul) API is provided in Section 411 of this document

32 REGISTERING AS A USER

Authentication to the SDP-V service is provided via the CDC Secure Access Management Service (SAMS)4 If you receive an error message after entering your credentials into SAMS please email surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership If you do not have a SAMS account you will need to obtain one before you can register as a user with SDP-V

321 VIEWER If your only need is to view search and export published SDP-V content you may simply follow the access instructions in Section 31 to get started

322 AUTHOR In order to become an SDP-V Author users should work with their program leadership to request the ability to author content If you are uncertain who to contact contact the SDP program (see Section 7) for assistance Registering to become an SDP-V Author involves the prospective user accepting an invitation from SAMS providing information to CDC and review of this information by CDC Please allow time for your request to be reviewed and approved

323 PUBLISHER Because Publishers have the important duty of ensuring quality and encouraging harmonization they are identified when a CDC program commits to using SDP-V to author questions and response sets needed to address their data collection needs The SDP program calls this ldquoprogram onboardingrdquo Therefore SDP-V Publishers are normally designated by the associated CDC program during the program onboarding process After this onboarding process changes to Publishers can be made by sending an email request to the SDP program (see Section 7)

4 For more information about SAMS please visit httpsauthcdcgov

Page 13 of 58

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 12: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

o Published ndash Content must be reviewed and approved by a Publisher (seeSection 233 in SDP-V to move into Published workflow status

Visibility Published content is visible to everyone who has access toSDP-V

Ability to Modify Content Only the Author or group members ofPublished content may choose to revise it This creates a new version ofthe content in draft status SDP-V maintains a version history for contentso that users can see how content has evolved over time

Note Published content is not necessarily authoritative andcontributions from external (ie outside CDC) partners should becoordinated by associated CDC programs Published content indicatesthat a program was ready to share content with others to promotetransparency harmonization standardization and the goals of SDP-VSDP-V is developing features that will be available in future release thatwill help users curate content and help programs identify preferredquestions and response sets to use in future data collection instruments

26 OPERATIONAL STATUS

The current version of SDP-V is the first major production release representing a minimally viable set of features Future releases will incorporate additional capability development based on feedback and feature requests from existing and future users

27 SECTION 508 COMPLIANCE AND ACCESIBILITY FEATURES

The current version of SDP-V has been tested according to HHS Section 508 Subparts B through D In order to meet the requirements of users requiring assistive technologies the following accessibility and compatibility features have been implemented in the application

bull Screen-reader-only text that allows the purpose of icons links and otherelements to be clear to non-sighted users

bull Skip navigation links

bull Tab index hierarchy on HTML elements that supports logical tab order to usersviewing the application with stylesheets disabled or without use of a mouse

bull Aria labels and titles where appropriate to make sure all forms and objects areaccessible through assistive technologies

bull High visibility contrast and color settings that conform to 508 standards aschecked with the WAVE compliance tool

bull In application help documentation that details all of the features of the applicationin plain ASCII text

bull Data tables with appropriately scoped column headers for screen readeraccessibility

Page 12 of 58

SDP Vocabulary Service

3 GETTING STARTED

This section serves as a quick reference for basic access and account configuration actions

31 ACCESSING SDP-V

The SDP-V service is accessible via a web browser by visiting the following URL httpssdp-vservicecdcgov A user account is not required to browse search and view content in the service that has been published A user account is required to author content or view content that is in draft status

Information on registering as a user is contained in Section 32 Information on accessing the content in the service via a Representational State Transfer (RESTFul) API is provided in Section 411 of this document

32 REGISTERING AS A USER

Authentication to the SDP-V service is provided via the CDC Secure Access Management Service (SAMS)4 If you receive an error message after entering your credentials into SAMS please email surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership If you do not have a SAMS account you will need to obtain one before you can register as a user with SDP-V

321 VIEWER If your only need is to view search and export published SDP-V content you may simply follow the access instructions in Section 31 to get started

322 AUTHOR In order to become an SDP-V Author users should work with their program leadership to request the ability to author content If you are uncertain who to contact contact the SDP program (see Section 7) for assistance Registering to become an SDP-V Author involves the prospective user accepting an invitation from SAMS providing information to CDC and review of this information by CDC Please allow time for your request to be reviewed and approved

323 PUBLISHER Because Publishers have the important duty of ensuring quality and encouraging harmonization they are identified when a CDC program commits to using SDP-V to author questions and response sets needed to address their data collection needs The SDP program calls this ldquoprogram onboardingrdquo Therefore SDP-V Publishers are normally designated by the associated CDC program during the program onboarding process After this onboarding process changes to Publishers can be made by sending an email request to the SDP program (see Section 7)

4 For more information about SAMS please visit httpsauthcdcgov

Page 13 of 58

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 13: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

3 GETTING STARTED

This section serves as a quick reference for basic access and account configuration actions

31 ACCESSING SDP-V

The SDP-V service is accessible via a web browser by visiting the following URL httpssdp-vservicecdcgov A user account is not required to browse search and view content in the service that has been published A user account is required to author content or view content that is in draft status

Information on registering as a user is contained in Section 32 Information on accessing the content in the service via a Representational State Transfer (RESTFul) API is provided in Section 411 of this document

32 REGISTERING AS A USER

Authentication to the SDP-V service is provided via the CDC Secure Access Management Service (SAMS)4 If you receive an error message after entering your credentials into SAMS please email surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership If you do not have a SAMS account you will need to obtain one before you can register as a user with SDP-V

321 VIEWER If your only need is to view search and export published SDP-V content you may simply follow the access instructions in Section 31 to get started

322 AUTHOR In order to become an SDP-V Author users should work with their program leadership to request the ability to author content If you are uncertain who to contact contact the SDP program (see Section 7) for assistance Registering to become an SDP-V Author involves the prospective user accepting an invitation from SAMS providing information to CDC and review of this information by CDC Please allow time for your request to be reviewed and approved

323 PUBLISHER Because Publishers have the important duty of ensuring quality and encouraging harmonization they are identified when a CDC program commits to using SDP-V to author questions and response sets needed to address their data collection needs The SDP program calls this ldquoprogram onboardingrdquo Therefore SDP-V Publishers are normally designated by the associated CDC program during the program onboarding process After this onboarding process changes to Publishers can be made by sending an email request to the SDP program (see Section 7)

4 For more information about SAMS please visit httpsauthcdcgov

Page 13 of 58

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 14: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

324 ADMINISTRATOR Administrator privileges are rewarded selectively at the platform level due to the responsibilities associated with admin users A request for the administrator role should only be made if a user requires the abilities outlined in Section 6

33 LOGGING IN

Once you access SDP-V via your browser at the web address given in Section 31 click the Login button at the top right of the screen You will be redirected for authentication through the SAMS portal

Upon authenticating via SAMS you will be redirected back to the SDP-V Service and logged into the system provided you have been given access to the service through SAMS

Note If you receive an error message after entering your credentials into SAMS pleaseemail surveillanceplatformcdcgov to request Surveillance Data Platform Vocabulary Service SAMS Activity Group membership

Page 14 of 58

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 15: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

34 SELECTING A PROGRAM AND SURVEILLANCE SYSTEM

Users of SDP-V can select the program and surveillance system they support to associate it with their SDP-V account This information will populate metadata in the system regarding which programs and surveillance systems are using particular content A user may select and change the program and system selection at any time via the applicationrsquos Settings menu

To select your Program and Surveillance System

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 Select ldquoSettingsrdquo to bring up the account details dialog window

3 Select the Program and Surveillance System you support by clicking on them in thelist You may search for Programs and Surveillance Systems by name by typing insearch keywords in the ldquoSearch Programshelliprdquo or ldquoSearch Systemshelliprdquo text boxesrespectively

NOTE Data from user settings will be used as default to populate system and program values These can be modified at any time by going to the user settings If you are collaborating with other users and created content that should be associated with a surveillance system or program that are different from yours those values can be modified in the user interface For example if your default program is ldquoNationally Notifiable Diseasesrdquo but the survey you are collaborating on is for the ldquoHepatitisrdquo program you can associate that survey with the ldquoHepatitisrdquo program through the UI without changing your user settings More information about this feature can found in Section 444

Page 15 of 58

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 16: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

4 Click ldquoUpdaterdquo to confirm your selections

If the System or Program you wish to identify your content with is not listed or you note Systems or Programs that are no longer active contact the SDP program to request that the list be updated (see Section 7) It is important for the accuracy of this list to be maintained

Page 16 of 58

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 17: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

35 NAVIGATION OVERVIEW

When you first access the SDP-V application you will see the SDP-V Dashboard screen pictured below

At the top of each SDP-V page is a navigation header Depending on your user role (Viewer Author Publisher or Administrator) the options you see in the navigation header will differ Viewers will see a Login button and Help menu If you are an Author Publisher or Administrator you will see (from left to right)

1 Button to navigate back to the Dashboard2 Drop-down menu to Create different types of content (see Section 44)3 Alerts if others have commented on your content4 Settings menu (drop-down from your username)5 Help menu

The Dashboard also contains

6 Search bar (see Section 41)7 Advanced filter options (See Section 42)8 Filter by type of Content (see Section 411)9 Search results10 ldquoMy Stuffrdquo panel (See Section 412)11 Filter content by Group (See 413)

More information about search functionality in SDP-V can be found in Section 41

When navigating between pages in SDP-V you may use the back button in your browser or the Back-arrow buttons within the application to go back to the previous page you viewed

Page 17 of 58

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 18: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

36 LOGGING OUT

To log out of the application

1 Click on the drop-down menu with your account name in the top-right corner ofthe application

2 From the drop-down menu click the Logout option

Logging out will return you to the SDP-V Dashboard

Page 18 of 58

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 19: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

4

SDP Vocabulary Service

INSTRUCTIONS FOR SDP-V USE

The following sections contain detailed step-by-step instructions along with screenshots to walk a user through how to use SDP-V capabilities

41 SEARCHING FOR CONTENT

The SDP-V Dashboard is the first screen presented to a user when they access the application You may access the dashboard at any time by clicking the ldquoDashboardrdquo button in the header of the application as described in more detail in Section 35 From the SDP-V Dashboard users have the ability to search for content by keywords or phrases

To search for content

1 Add a keyword or phrase to the search input field (circled in red in the abovescreenshot)

2 While typing a dropdown list of suggestions based on the names of items in thesystem may display to assist with content discovery (see the screenshot below)

3 Click on the search icon or hit the Enter key4 The list of Search Results below will be updated to reflect your search terms5 The results are prioritized by relevance Items with the same relevance are

secondarily sorted by the number of unique systems that are using the item onpublished surveys The search term is highlighted wherever it appears in searchresults (indicated by red arrows in the above screenshot)

Page 19 of 58

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 20: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

411 FILTERING BY TYPE OF CONTENT If you would like to search for a particular type of content (eg just response sets questions sections or SDP-V surveys) SDP-V allows you to filter search results by content type You may do so by selecting a content type in the analytics widget on the dashboard The analytics widget (outlined in red in the below screenshot) appears below the search bar and lists counts of each type of content in the system

To filter your search results by content type

1 Select the desired type (eg Response Sets Questions Sections or Surveys) fromthe analytics widget

2 Your selection will become highlighted and the list of search results will be updated to reflect your selection

3 Select ldquoClear Type Filterrdquo to remove the content type filter and search across alltypes of content

Page 20 of 58

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 21: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

412 FILTERING TO ldquoMY STUFFrdquo The user has the ability to focus search results on the content they have authored via the ldquoMy Stuffrdquo panel on the right-hand side of the SDP-V Dashboard

To filter by content you have authored 1 Select a desired content type from the ldquoMy Stuffrdquo panel on the right2 The analytics widget and results list will update with content that matches your

selection3 Select ldquoClear My Stuff Filterrdquo option in the ldquoMy Stuffrdquo panel to remove your filter

Page 21 of 58

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 22: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

413 FILTERING BY GROUP The user has the ability to filter content returned from search results based on if the content belongs to a group that contains the user If the user is logged in and belongs to an authoring group on the dashboard the user will see a ldquoFilter by Grouprdquo dropdown menu (under the My Stuff panel) with a list of the groups that the user belongs to

1 Select group from ldquoFilter by Grouprdquo dropdown2 To view the description and list of members for the group selected in the group

filter dropdown click the expand icon next to ldquoFiltering by content in grouprdquo

42 ADVANCED SEARCH FEATURES

The advanced search features allow the user to further refine and filter how search results are displayed on the dashboard Multiple advanced search filters may be used at the same time To open the Advanced Search Filters dialog window

1 Select ldquoAdvancedrdquo from underneath the search bar

The advanced search filters are described in more detail below

Page 22 of 58

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 23: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

421 FILTERING BY PROGRAM SURVEILLANCE SYSTEM OR BOTH The Advanced Search feature allows users to find content associated with a specific program surveillance system or combination of the two

To filter by program system or both

bull Select the desired Programs and Systems by clicking on them If needed you canselect multiple items within the list by holding down the ldquoShiftrdquo ldquoControlCTRLrdquoor ldquoCommandCMDrdquo keys before clicking You may also use the search fields torefine the displayed list of programs and systems

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters applied and viewsearch results across all Programs and Systems

Page 23 of 58

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 24: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

422 SORTING CONTENT The user has the ability to sort the search results by various priority By default the most relevant search results (based on the frequency the search terms show up in the item) are displayed at top Items with the same relevance are secondarily sorted by the number of unique systems that are using the item on published surveys To change how to search results are sorted bull Select ldquoSystem Usagerdquo or ldquoProgram Usagerdquo from Sort By dropdown menu

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 24 of 58

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 25: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

423 MOST RECENT VERSION FILTER By default all versions of content that best match the keyword or phrase that the user typed into the search input field are returned in the search results If the most relevant content has many versions the top search results that are displayed may only be different versions of the same response set question section or survey and other relevant matches in SDP-V may not be visible at the top of the search results The ldquomost recent versions onlyrdquo filter limits search results to the most recently published version of other usersrsquo content and to the userrsquos own most recent version of draft content To filter by most recent version bull Check the box next to ldquoMost Recent Versions Onlyrdquo

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

bull Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

NOTE Consider using this filter when creating or revising SDP-V surveys because it is likely that the user will want to use the most recent version of vocabulary (as opposed to when a user is adding existing content to the SDP-V repository) This feature is especially valuable when searching for PHIN VADS value sets because many versions of PHIN VADS value sets exists in SDP-V

Page 25 of 58

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 26: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

424 CONTENT CHANGED SINCE FILTER This filter allows the user to select a date if you wanted to only see content revised or created recently (from the date selected forward) To only view content that has been revised since a particular date bull Either select a date from the calendar (Date picker pictured below) or type in a

date in MMDDYYYY format

bull Click ldquoCloserdquo to dismiss the window and view an updated list of results on thedashboard Your selections will appear in the search results list

Page 26 of 58

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 27: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

1) Select ldquoClear Adv Filtersrdquo to remove any of the advanced filters

Page 27 of 58

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 28: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

43 VIEWING DETAILS OF EXISTING CONTENT

Each piece of content in SDP-V is represented in search results by a content widget (as shown in the below screenshot) Content widgets give the following information

1 The content title2 Number of Programs and Systems associated and the workflow status (Draft or

Published) of the content type3 The creation date version number and content type4 Linked or associated content (Questions may be linked to Response Sets Sections

may contain Questions and Surveys may contain Sections)

From the content widget there are two methods to view additional details about the content

1 Clicking on the Linked Item bar at the bottom of the widget expands this sectionof the widget to display additional information about linked content

2 Clicking the eye icon at the top right of the widget allows you to navigate to thedetails page for the content

Navigating to a details page gives you a complete summary of the content including version history (left panel) author and publisher (if applicable) description and contents associated tags (if applicable) linked content and program and surveillance system usage

Page 28 of 58

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 29: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

Page 29 of 58

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 30: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

44 DRAFTING NEW CONTENT

If you have Author or Publisher privileges in SDP-V you will see a ldquoCreaterdquo dropdown menu in the header at the top of the application This dropdown menu will be your starting place for creating new Response Sets Questions Sections or Surveys from scratch

441 DRAFTING NEW QUESTIONS

Page 30 of 58

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 31: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

To draft a new question

1 Type in the question text (Example What day were you sick)2 Give the question a description ensure you add terms that are specific to your

question This will help support search and filtering3 Select a Category the category will define the type of question you are creating

The categories include ldquoDemographicsrdquo ldquoClinicalrdquo ldquoTreatmentrdquo ldquoLaboratoryrdquoldquoVaccinerdquo ldquoEpidemiologicalrdquo and ldquoEmergency Preparednessrdquo

a For some of the categories (those with a secondary list of subcategories)when they are selected another dropdown appears with a list ofsubcategories linked to that category

4 Choose a Response Type that indicates what kind of response is expected for thequestion These response types are defined in the HL7 ldquoQuestionnaireItemTyperdquovalue set5

5 (Optional) Select ldquoOther Allowedrdquo This choice appears when the ldquoChoicerdquo orldquoOpen Choicerdquo Response Type is selected When checked it indicates that thequestion provides an ldquootherrdquo choice where a respondent can provide their ownanswer outside of the chosen Response Set

6 Add Tags to facilitate content discovery and reuse When you type in the first ldquoTagTyperdquo field a list of suggested tags used on other content will appear Tags arekeywords from a controlled vocabulary applied to a question to help facilitatefinding relevant questions during a search For instance if you are authoring aquestion about multiple drug resistance Escherichia coli tagging the question withthe SNOMED-CT code for multiple antimicrobial drug resistant bacteria may helpothers who need to collect data about multiple drug resistant organisms in thefuture

a The columns in the tags table are defined as followsi Tag Name Keywords from a controlled vocabulary A controlled

vocabulary includes external code systems such as LOINC orSNOMED-CT or internally developed vocabularies

ii Tag Value This may be a text or coded value that comes from acontrolled vocabulary Note that if you have selected a tag that hasalready been used in SDP-V or is selected from the results fromldquosearch for coded tagsrdquo this field will be automatically populated

iii Code System Identifier (optional) The Code System used if you areusing a coded value (eg LOINC SNOMED-CT RxNorm) Note thatif you have selected a tag that has already been used in SDP-V or isselected from the results from ldquosearch for coded tagsrdquo this fieldwill be automatically populated

5 The HL7 QuestionnaireItemType value set describes the type of data expected in response to questions More details about this value set can be found at httpswwwhl7orgfhirvalueset-item-typehtml

Page 31 of 58

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 32: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

b See Section 442 point 4 for more detail on how to search for coded valuesthrough SDP-V

7 If you chose ldquoChoicerdquo or ldquoOpen Choicerdquo as the Response Type in Step 4 thismeans that you expect responses to the question to come from a defined set ofresponses You will be able to search through existing Response Sets in the systemand associate them with the Question you are creating if they are applicable Toselect a specific Response Set click the ldquoAddrdquo button (shown as a + sign) Onceadded the + sign will change into a checkmark to indicate the response set will beassociated with the question on save

8 The selected Response Sets panel displays your selections Adding a Response Setto a question simply means that the Response Set may be a valid set of choices forthe question You can add more than one Response Set if appropriate

a Response sets added to a question at the time of creation by the authorwill be displayed in the UI on the Question Details page as ldquoAuthorRecommended Response Setsrdquo This allows authors to identify ResponseSets that are appropriate for different contexts (eg For a question askingabout a vaccine administered valid response sets may include condition-specific vaccine types like varicella influenza or pertussis) TheseResponse Sets associated by the question author will populate theResponse Set drop down menu on the ldquoCreate Sectionrdquo page to encouragereuse of the same response sets (See Section 443 Step 4)Note If a user would like reuse a question but the response set(s)associated with the question at the time of creation by the original authordo not meet the needs of that user users can select other Response Setsfrom the repository to associate with the question while creating editingor revising a Section (See Section 443) This allows other SDP-V users toreuse questions in the repository but provides the flexibility to select acontext appropriate Response Set on a given section Response sets linkedto a question on a Section will appear in the UI on the Question Detailspage under ldquoResponse Sets Linked on Sectionsrdquo This allows users to see allof the response sets that have been associated with a particular questionon different sections in SDP-V

9 If you would like to associate a new response set with the question you may do soby clicking the ldquoAdd New Response Setrdquo button This will bring up the NewResponse Set dialog Section 442 describes the fields available to you duringresponse set creation

All fields are optional other than the main ldquoQuestion texthelliprdquo field however you should complete as many fields as possible

Page 32 of 58

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 33: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

442 DRAFTING NEW RESPONSE SETS

To draft a new Response Set

1 Give the Response Set a descriptive name (Example Gastrointestinal Symptoms)2 Give the Response Set a detailed description ensuring you add terms that are

specific to your response set This will help support search and filtering3 Add a Display Name (Example Abdominal Pain Vomiting Diarrhea etc) This is

the human-readable value for the response4 If applicable add a Response Code This may come from your programrsquos internal

coding scheme or from an external code system such as LOINC or SNOMED-CTRather than requiring you to remember or copy and paste codes from othersystems SDP-V allows you to search for codes from such external code systems byclicking on the magnifying glass icon to the left of the Display Name field Thisopens up the Search Codes dialog box shown below You may select a particularcode system from the drop down menu or enter a search term to search acrossmultiple code systems This code search functionality searches codes from PHINVADS You may add coded values from these search results to your response setby clicking the ldquoAddrdquo selection beside each result

Page 33 of 58

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 34: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

5 If you are using a coded value specify the Code System used (Example the nameof your programrsquos coding scheme LOINC SNOMED-CT RxNorm etc) Note that ifyou used the code lookup capability described in Step 4 above to add responses toyour response set SDP-V will automatically fill out the code system correspondingto each response added in this way

Clicking the ldquo+rdquo icon allows you to add multiple rows to the table Note that SDP-V allows you to mix responses from multiple code systems along with non-coded responses within a single response set

All fields are optional except for the first ldquoNamerdquo field however you should complete as many fields as possible

Page 34 of 58

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 35: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

443 DRAFTING NEW SECTIONS bull Recall that a section is a grouping of questions related to a topic (eg

demographic clinical laboratory epidemiological) and intended to appeartogether as part of a data collection instrument A section may also contain one ormore sections (eg sub-sections or nested sections) For instance ldquoSymptomrdquoand ldquoDiagnosisrdquo sections within a ldquoClinicalrdquo section

To draft a new Section

1 Give the Section a name that reflects the type of content you are categorizing(Example Meningococcal Disease Vaccination Information)

2 Add a description to the Section Ensure you add terms that are specific to yourSection This will help support search and filtering

3 Add Tags to the section to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

4 You will be able to search through existing Questions in the system and add themto the Section you are creating To search questions select the ldquoQuestionsrdquo searchtab and enter your search terms or phrase To select a specific Question click the

Page 35 of 58

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 36: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

ldquoAddrdquo button (shown as a + sign) Once added the + sign will change into a checkmark to indicate the question will be associated with your section on save

5 You will be able to search through existing Sections in the system and add them tothe Section you are creating This allows users to nest sections to show the parent-child relationship between content Nested sections may be used to createldquorepeating groupsrdquo sub-sections templates etc To search sections select theldquoSectionsrdquo search tab and enter your search terms or phrase To select a specificSection click the ldquoAddrdquo button (shown as a + sign) Once added the + sign willchange into a checkmark to indicate the section will be associated with yoursection on save

6 The selected Questions amp Sections panel displays your selections7 As you are building your Section you can associate Response Sets with the

selected questions Select from the Response Set drop down to see availableResponse Sets or Search a list of pre-existing Response Sets by clicking on themagnifying glass icon As mentioned in 441 point 8 the Response Sets providedin the drop down are those that the question author associated with the question

8 Clicking the ldquoAdd New Response Setrdquo allows you to draft a new Response Set Youcan then associate it with a desired Question on your section by clicking on themagnifying glass icon

9 To organize the selected Questions use the Up and Down arrows10 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository11 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

12 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

Note All fields are optional except the first ldquoSection Namerdquo field however you should complete as many fields as possible

Page 36 of 58

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 37: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

444 DRAFTING NEW SURVEYS Recall that an SDP-V Survey is one or more Sections with questions that are combined together and intended for a data collection instrument or information exchange

To draft a new Survey

1 Give the Survey a name the naming convention should reflect the type of Surveyyou are creating (Example Perinatal HIV Exposure Survey)

2 Add a description to the Survey Ensure you add terms that are specific to yourSurvey This will help support search and filtering

3 If the Survey has OMB Approval add the OMB Control Number The OMB numbermust be entered in the following format ldquo-rdquo

4 The Program and System will be populated from the authorrsquos account detailspage however the system and program associated with content can be modifiedin the user interface by clicking the ldquoeditrdquo icon

5 Add Tags to the survey to assist with content discovery during search For moreinformation on Tags see section 441 point 6 where tagging is explained in detailin the draft question summary

6 The Sections panel displays your selections

Page 37 of 58

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 38: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

7 Type in a search term or phase to find relevant Sections to add to your survey Toadd more Sections to your Survey click the ldquoAddrdquo button (shown as a ldquo+rdquo) Onceadded the + sign will change into a checkmark to indicate the section will beassociated with your survey on save

a Note New Sections cannot be created directly from the ldquoCreate Surveyrdquo orldquoEdit Surveyrdquo page If you would like to add a section to your Survey itmust already exist in the repository You may need to return to thedashboard to create the section that you want to add your survey Oncecreated you can return to this page to add that section to your survey

8 To organize the selected Questions use the Up and Down arrows9 To remove a selected Question or Section from your section select the ldquoTrashrdquo

icon This does not delete that Question or Section from the repository10 Click on ldquoAdd New Questionrdquo to launch the draft new question dialog to add a

question to your section that does not exist in the repositorya Note New Sections cannot be created directly from this ldquoEdit Sectionrdquo

page If you would like to add a section to your section it must alreadyexist in the repository You may need to return to the dashboard to createthe section that you want to add as a nested section or sub-section Oncecreated you can return to this page to add that section to your section

11 Click ldquoSaverdquo to create your section or ldquocancelrdquo to delete the section withoutsaving

All fields are optional except the first ldquoSurvey Namerdquo field however you should complete as many fields as possible

Page 38 of 58

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 39: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

45 IMPORTING NEW CONTENT

For support with importing content including an example template please contact the SDP team (See Section 7)

451 Message Mapping Guide (MMG) This feature is to support the bulk import of vocabulary content from Nationally Notifiable Disease Message Mapping Guides (MMGs) On the taskbar there is an action button to create content To create a SDP-V survey using content from a Message Mapping Guide (MMG) formatted spreadsheet execute the following steps

bull Click on the Create button on the Vocabulary service taskbar and select Import MMG

bull Select the MMG formatted file you wish to import using the file explore by clickingBrowsehellip

Page 39 of 58

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 40: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

4511 Message Mapping Guide (MMG) Import Template The following table shows the expected MMG Column Names and how they map to Vocabulary Service Each column is necessary for import even if left blank Each column should be spelled exactly as appears in quotes in the table below

MMG column name with associated vocabulary service item

MMG Column Vocabulary Service Item Name

lsquoData Element (DE) Namersquo Question Name

DE Identifier Sent in HL7 Message Data Element Identifier Tag on Question

Data Element Description Question Description

DE Code System Code System Identifier for Data Element Identifier Tag on Question

Response Set

Value Set Name (VADS Hyperlink)

Note The DE will be associated with the PHIN VADS value set if a hyperlink is provided The importer does not check the validity of PHIN VADS hyperlinks as of Release 18 If a hyperlink is not provided the importer will look for a tab with the same name as the value in this cell If a tab with the same name is not found the following error will be displayed Error Value set tab XXX not present

PHIN Variable Code System OR Local Variable Code Program Defined Variable Name associated with a question

System

PHIN Variable

PHIN data element identifier (leave blank if local) The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in this column or you will receive the following error ldquoError This Excel file does not contain any tabs with the expected mmg column name format and will not be imported Refer to How to Identify Sections Templates or Repeating Groups in the Import Content Help Documentation for more informationrdquo

Data Type Question Response Type

bull The section ldquoStartrdquo and ldquoEndrdquo markers must be contained in the ldquoPHIN Variablerdquo column

bull The content in each tab in the spreadsheet that contains all required columns will beimported and tagged with Tab Name

bull If there are multiple spreadsheets that contain all required columns they will be imported as separate sections on the same SDP-V survey

bull The user importing content into SDP-V using this template will be assigned as the authorof the survey

bull Content will be imported into SDP-V in DRAFT status

NOTE If a required column from the table is missing the user will receive an error message and the content will not be imported

Page 40 of 58

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 41: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template

Sections templates or repeating groups are created by listing data elements between START insert section name and END insert section name rows Each row between these markers are imported as data elements within that grouping (called sections in the vocabulary service) Sub-sections or sub-groupings may be created by including additional START and END markers within a parent section or grouping

bull The section ldquoSTARTrdquo and ldquoENDrdquo markers must be contained in the ldquoPHIN Variablerdquocolumn

bull The beginning of a section is indicated by the prefix START (including a space after thecolon)

bull The end of a section is indicated by the prefix END (including a space after the colon)bull The text following the START and END pre-fixes will be imported as the Section

Name in the vocabulary servicebull The section name following the START prefix must exactly match the section name

following the END prefix in order for the section to be correctly importedbull Notes should not be included in the same row as the section name (eg after the

lsquoSTARTrsquo or lsquoENDrsquo pre-fixesrsquo)

Page 41 of 58

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 42: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

46 REVISING AND EDITING CONTENT

Users may edit their own draft content or revise their own published content Editing draft content allows you to make any changes to it as needed before it is published Revising published content creates a new version of that content in draft form maintaining the history of the previous published version

To revise Published content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history at the left-hand

side of the details view page4 Click the ldquoReviserdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may edit the content for each field as needed

5 Click ldquoSaverdquo to confirm your changes6 Saving your changes creates a new version of the content in a draft state

To edit Draft content

1 Find the content you wish to edit2 Navigate to the content details view3 Select the latest version of the content from the version history panel at the left-

hand side of the details view page4 Click the ldquoEditrdquo button This will bring you to the authoring page for the content

with fields prepopulated based on what was previously filled in for the content5 Click ldquoSaverdquo to confirm your changes6 Edits to draft content is captured and can be viewed on the change history tab for

that content

Page 42 of 58

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 43: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

a Note As of Release 18 the change history tab will track changes made toresponse set question section or survey fields but not associationsChanges to the following object associations are not currently tracked onthe ldquochange historyrdquo tab tags changes to program defined variableaddition or removal of sections questions or response sets changes to aresponse set linked to a question on a section

Page 43 of 58

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 44: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

47 EXTENDING CONTENT

Users may extend published content meaning that they may create a draft copy of that content to use as a starting point for their own content Unlike revising and editing you do not need to be the author of a piece of content to extend it

To extend existing content

1 Find the published content you wish to extend2 Navigate to the content details page3 Click the ldquoExtendrdquo button This will bring you to the authoring page for the

content with fields prepopulated based on what was previously filled in for thecontent You may update content in any field as necessary

4 Click ldquoSaverdquo to confirm your changes5 Saving an extension will save a draft that is the first version (new version history)

with a link to the content it was extended fromWhen you eventually request that a publisher review your content (see Section 410) you will be asked to share why you chose to extend rather than reuse existing content

48 ADDING CONTENT TO GROUPS

Users may add content they own to a group that they are a member of by navigating to the details page of the content and selecting the name of the group from the ldquoGroupsrdquo dropdown menu in the action buttons bar at the top right of the content pane Only the groups that a user is a member of will be displayed in the drop-down menu

Page 44 of 58

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 45: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

49 COMMENTING ON EXISTING CONTENT

Users may post comments on existing content in the system as well as reply to othersrsquo comments

To post a public comment to a content type

1 Navigate to the details view page for the content you would like to comment on2 Scroll to the bottom of the page3 In the ldquoYour Commentrdquo field type the comment you would like to make4 Click the ldquoPostrdquo button to display your comment along with a timestamp Your

comment will be visible to other users of the system The author of the contentwill be notified of your comment when they next access SDP-V

Page 45 of 58

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 46: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

410 EXPORTING CONTENT

Authenticated SDP-V users can export surveys andor sections into the following formats Epi Info-compatible XML REDCap6 -compatible XML spreadsheet (XLSX) and PDF Viewers (unauthenticated users) can only print published content to PDF

4101 Epi Info (Surveys and Sections) On the view pages for surveys and sections there is an action button that exports the current content to Epi Info (XML) To export a survey or section and use it in Epi Info execute the following steps

bull Click on the Export button on the Vocabulary service section details page (this willsave a xml file to the folder your browser directs downloads)

bull Open Epi Infobull Choose the option to Create Formsbull From the File menu select Get Templatebull Select the xml file you downloaded from the vocabulary service it will be in the

folder your browser downloads content into (usually the Downloads folder) ClickOpen

bull From the File menu select New Project from Templatebull After selecting the template that was created from the vocabulary service xml file

complete the rest of the fields Click Ok

4102 REDCap (Surveys and Sections)On the view pages for surveys and sections there is an action button that exports the current section to REDCap To export a survey or section and use it in REDCap execute the following steps (exact wording may differ slightly based on your version of REDCap)

bull Click on the Export button on the Vocabulary service survey or section details pageand select REDCap (XML) (this will save a xml file to the folder your browser directsdownloads)

bull Open up REDCapbull Choose the option to create a new projectbull On the project creation page follow the on screen instructions to add a name and

various attributes to the new projects

6REDCap is a secure web application for building and managing online surveys and databases Visit project-redcaporg for more info

Page 46 of 58

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 47: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

bull Look for an option titled something similar to Start project from scratch or beginwith a template and choose the Upload a REDCap project XML file option

bull Click the Choose File button to select the xml file you downloaded from thevocabulary service it will be in the folder your browser downloads content into(usually the Downloads folder)

bull After selecting the xml file to import and filling out the rest of the fields click on theCreate Project or Start Project button at the bottom of the page

4103 Spreadsheet (XLSX) (Surveys only)On the view page for surveys there is an action button that exports the current survey to spreadsheet format (xlsx) To export a survey into this format execute the following steps bull Click on the Export button on the Vocabulary service survey or section details page

and select Spreadsheet (XLSX) (this will save a xlsx file to the folder where yourbrowser directs downloads)

4104 PDF (Surveys and Sections)On the view page for surveys and sections there is an action button that exports the current content to a PDF file To export a section or survey into this format execute the following steps

bull Click on the Export button on the Vocabulary service survey or section details pageand select Print (this will save a pdf file to the folder your browser directsdownloads)

411 ACCESSING CONTENT VIA THE SDP-V APPLICATION PROGRAMMING INTERFACE (API)

The SDP-V API is documented in using the Swagger format This format allows SDP-V to generate a documentation web site which can be found at httpssdp-vservicescdcgovapiindexhtml This web site provides developers with the information they need to build applications that access information in SDP-V Additionally the Swagger document provided on the site can be used by software development tools to generate source code to access the service To see a list of environments supported by the Swagger code generation environment visit httpsswaggerioswagger-codegen

Page 47 of 58

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 48: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

412 REQUESTING THAT CONTENT BE PUBLISHED

SDP-V Authors may not publish their own content rather they must reach out to a Publisher to request that their draft content be published

To submit your content for publishing

1 Find the draft content you wish to publish2 Navigate to the details view page3 Click the ldquoSend to Publisherrdquo action button at the top right of the details view

page4 Select the Publisher that supports your program from the list Authors are

expected to know which Publisher supports their program 5 Selecting a publisher will bring up a prepopulated email message within the email

client configured in your system (typically Outlook) Include in this email messagea justification for why it was necessary for you to create new content rather thanreuse existing content and a need-by date for publishing

6 Click ldquoSendrdquo in the email message to notify the Publisher that your content isready for review

Page 48 of 58

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 49: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

5 PUBLISHER FUNCTIONS

Publishers are responsible for reviewing content created by SDP-V Authors on the program they support and making determinations of whether such content is ready to be published

51 FIND OTHERSrsquo DRAFT CONTENT

As an SDP-V Publisher you will be able to view all draft content in the system regardless of who authored it When an Author is ready for their content to be reviewed they will notify you via an email This email will contain a link to the specific content for your review as well as a justification for why new content was needed (rather than reuse) and a need-by date for your review

Clicking on the link in the email message will take you to details view page of the draft content for your review

Once you have completed your review notify the Author of the outcome of their request via email

52 PUBLISH DRAFT CONTENT

Once you have reviewed draft content and determined that it is ready to be published you can do so by clicking on the ldquoPublishrdquo action button at the top right of the details view page for that content

Note that publishing a piece of content will also publish any lower-level pieces of content associated For example publishing a Section will also publish any sub-sections Questions and Response Sets on that Section

Page 49 of 58

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 50: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

6

SDP Vocabulary Service

ADMINISTRATOR FUNCTIONS

If a user has the Admin role when they click on their email in the navigation bar they will see a link to the Admin Panel page

The admin panel currently has the following functions

61 ADMIN LIST amp PUBLISHER LIST TABS

The ldquoAdmin Listrdquo tab on the Admin Panel allows the user to add or remove admin privileges from users by entering their email in the text field and clicking the + button or by clicking the remove button next to their name The ldquoPublisher Listrdquo tab behaves the same way but is for granting or removing the Publisher role to an account

62 PROGRAM LIST amp SYSTEM LIST TABS

The ldquoProgram Listrdquo and ldquoSystem Listrdquo tabs operate the same way These tabs exist for users that request a new program or system be added to the application Adding a program or system here will allow for a user to associate their account and subsequently the content they create with a specific program or system

Page 50 of 58

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 51: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

63 ELASTICSEARCH TAB

This tab provides descriptions on the page of the two functions The first is to synchronize elasticsearch database records after an update takes place that requires records to be resynchronized (such as a change to the ES mapping) The second operation deletes the data from elasticsearch and resynchronizes everything which is only required rarely after large updates to the application

64 GROUP LIST TAB

This tab is used to add groups to the system and then curate the membership lists of those groups Use the input fields to add new groups by name and description After a group is added to the list you can use the ldquoManage Usersrdquo button (shown in the red box in the screen shot below) to add users to the group by email You may also remove users from the group using the ldquoRemoverdquo button on the group membership modal

Page 51 of 58

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 52: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

7

SDP Vocabulary Service

CONTACT US

You may contact the SDP team via email at surveillanceplatformcdcgov or via the ldquoContact Usrdquo link in the application

Page 52 of 58

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 53: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

APPENDIX A ACRONYMS

Acronym Definition

API Application Programming Interface CDC Centers for Disease Control and Prevention GUI Graphical User Interface MMG Message Mapping Guides OMB Office of Management and Budget PHIN VADS Public Health Information Network Vocabulary Access and Distribution

System REDCap Research Electronic Data Capture RESTFul Representational State Transfer SAMS Secure Access Management Service SDP Surveillance Data Platform SDP-V Vocabulary Service STLT State Tribal Local And Territorial

Page 53 of 58

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 54: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

SDP Vocabulary Service

APPENDIX B ROLE CAPABILITIES AND WORKFLOWS

Chart 1A Content Search to Publication

Chart 1B Content Import to Publication

Chart 2 Role Capabilities

Chart 3 Author Workflow Content Creation and Modification

Page 54 of 58

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 55: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

Chart 1A Content Search to Publication Use Case Creation of New Data Collection Instrument from ldquoblank pagerdquo in SDP-V

Author Role

All Users

Publisher Role

Start SEARCH For Content

1Does Returned Content Satisfy User Needs

Partly

Modify Existing content

Yes

REUSE Content in SDP-V

No

CREATE New DRAFT content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE

No Suggest changes

Make changes

End

Yes No

Return to 1

Search

To Chart 2 Visibility Rules

Submit Local Response Set to PHIN VADS (if appropriate)

Page 55 of 58

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 56: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

-

Chart 1B Content Import to Publication Use Case Creation of Data Collection Instrument in SDP-V from Existing Content

Authors

Start IMPORT Content into SDP-V

1Does Content Duplicate Existing

Questions and Response Sets in SDP V

Partly

EXTEND Existing

Yes Replace using Curation Wizard

REUSE Content in SDP-V

No

content

2Is DRAFT content ready for publication

Send request to Publisher with justification for not reusing content

Make changes

End Yes No

Submit Local Response Set to PHIN VADS (if appropriate)

Publisher Role

3Is content approved for publication

Yes

PUBLISH content

No 4Is there similar existing content in the service

Yes

Suggest REUSE of content

No

Suggest changes to content and provide justification

Return to 1

Page 56 of 58

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 57: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

Chart 2 Role Capabilities

Show all content in PUBLISHED workflow status plus show content in DRAFT

workflow status where user is

author or member of group content added to

Show all content in PUBLISHED workflow status

Yes

No

1Is the user aviewer (public)

3Is the user a publisher(authenticated user with publisher role)

Yes Show all content in DRAFT and PUBLISHED workflow status

No

2Is the user the authorof the content

(authenticated user with author role) or member of group content belongs to

Yes

Export to REDCap (XML)

Print to PDF

Export Content Browse Use Search and Advanced Search Features

Formats

Modify existing content

REUSE content

CREATE new content

Export Content

Browse

Use Search and Advanced Search Features

Comment

From Chart 1 Search

Change Content

Publish To Chart 1 Publisher Role

Same as Author Capabilities

Add Public Comment to Content

To Chart 3 Modify

To Chart 3 Create

Export to EpiInfo (XML)

Print to Spreadsheet (XLSX)

Page 57 of 58

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify
Page 58: VOCABULARY SERVICE (SDP-V) RELEASE 1.8 SURVEILLANCE …Aug 07, 2018  · 1 2 . SDP Vocabulary Service . INTRODUCTION AND PURPOSE OF THE SDP-V USER GUIDE . This document serves as a

Chart 3 Author Workflow Content Creation and Modification

content filled in for

1Does the userOWN the content

Modify existing content

No

EXTEND content

REUSE content

CREATE new content

From Chart 1 Search

Yes

Update content

Populate content

REVISE content

DRAFT copy of content created and fields prepopulated based on what was previously

Yes

2Is contentPUBLISHED

EDIT content

No

Save DRAFT Version 1 of content created

assigned a new unique SDP-V ID

Save DRAFT content updated Version number will not change

Save New Version of content in DRAFT state created

Cancel No changes to content

Cancel No changes to content

Cancel

No changes to content

EDIT content

Save DRAFT Version 1 of

content created assigned a new unique SDP-V ID linked to content it was extended from

Cancel

No changes to content

Modify

Create

Go to 2 on Chart 1

Go to 2 on Chart 1

Go to 2 on Chart 1

Add to Group Check for Duplicates

Extend Existing Content if you want to create a link to existingobject in service (eg if your questionRS is an extension of a

standard may want to link to it)

Page 58 of 58

  • 20180807_SDP-V_User_Guide_Final
    • 1 Introduction and Purpose of the SDP-V User Guide
    • 2 SDP-V Goal
      • 21 SDP-V Overview
      • 22 Types of Content in SDP-V
      • 23 System Roles And Capabilities Summary
        • 231 Viewer (Public)
        • 232 Author (Authenticated User)
          • 2321 AUTHOR Capabilities
          • 2322 AUTHOR EXPECTATIONS AND BEST PRACTICES
            • 233 Publisher (Authenticated User with Publisher Role)
              • 2331 PUBLISHER CAPABILTIES
              • 2332 PUBLISHER EXPECTATIONS AND BEST PRACTICES
                • 234 Administrator (Authenticated User with Admin Role)
                  • 2341 ADMINSTRATOR Capabilities
                      • 24 Collaborative Authoring Groups
                      • 25 Key Terms
                      • 26 Operational Status
                      • 27 Section 508 Compliance and Accesibility Features
                        • 3 Getting Started
                          • 31 Accessing SDP-V
                          • 32 Registering as a User
                            • 321 Viewer
                            • 322 Author
                            • 323 Publisher
                            • 324 Administrator
                              • 33 Logging In
                              • 34 Selecting a Program and Surveillance System
                              • 35 Navigation Overview
                              • 36 Logging Out
                                • 4 Instructions for SDP-V Use
                                  • 41 Searching for Content
                                    • 411 Filtering by Type of Content
                                    • 412 Filtering to ldquoMy Stuffrdquo
                                    • 413 Filtering by Group
                                      • 42 Advanced Search features
                                        • 421 Filtering by Program Surveillance System or Both
                                        • 422 Sorting Content
                                        • 423 Most Recent Version Filter
                                        • 424 Content Changed Since Filter
                                          • 43 Viewing Details of Existing Content
                                          • 44 Drafting New Content
                                            • 441 Drafting New Questions
                                            • 442 Drafting New Response Sets
                                            • 443 Drafting New Sections
                                            • 444 Drafting New Surveys
                                              • 45 Importing New Content
                                                • 451 Message Mapping Guide (MMG)
                                                  • 4511 Message Mapping Guide (MMG) Import Template
                                                    • 452 Content Organization How to Identify Sections Templates or Repeating Groups within the MMG Spreadsheet Import Template
                                                      • 46 Revising and Editing Content
                                                      • 47 Extending Content
                                                      • 48 Adding Content to Groups
                                                      • 49 Commenting on Existing Content
                                                      • 410 Exporting Content
                                                        • 4101 Epi Info (Surveys and Sections)
                                                        • 4102 REDCap (Surveys and Sections)
                                                        • 4103 Spreadsheet (XLSX) (Surveys only)
                                                        • 4104 PDF (Surveys and Sections)
                                                          • 411 Accessing Content via the SDP-V Application Programming Interface (API)
                                                          • 412 Requesting that Content be Published
                                                            • 5 Publisher Functions
                                                              • 51 Find Othersrsquo Draft Content
                                                              • 52 Publish Draft Content
                                                                • 6 Administrator Functions
                                                                  • 61 Admin List amp Publisher List Tabs
                                                                  • 62 Program List amp System List Tabs
                                                                  • 63 Elasticsearch Tab
                                                                  • 64 Group List Tab
                                                                    • 7 Contact Us
                                                                    • Appendix A Acronyms
                                                                    • Appendix B Role Capabilities and Workflows
                                                                      • UserGuide_AppB
                                                                        • Workflow1a
                                                                        • Workflow1B
                                                                        • Chart2 Capabilities
                                                                        • Chart3Modify