Data Mapping Utility (DMU)

Entity Editor

Introduction

The basic steps to create an Entity are:

1. Identify the source file(s) in VistA for the data model.
2. Assign an element tag to each field that will be returned.
3. Write any additional code needed for the Entity or individual elements, to perform specific tasks, such as a special lookup routine or data transformations.

Invoking the Editor

Use the Enter/Edit an Entity [DDE ENTITY ENTER/EDIT] option on the Data Mapping [DDE ENTITY MAPPING] menu to invoke a ScreenMan form to facilitate the creation or modification of Entities.

VA FILEMAN 22.2


SELECT OPTION: OTHER OPTIONS
SELECT OTHER OPTION: DATA MAPPING
SELECT DATA MAPPING OPTION: ENTER/EDIT AN ENTITY
	

You are then asked to select an Entity; you can also create a new one:

SELECT ENTITY: ZZPATIENT
  ARE YOU ADDING 'ZZPATIENT' AS A NEW ENTITY (THE 276TH)? NO// Y (YES)
	

The ScreenMan form launches, presenting the following pages and attributes for editing:

• Basic Information (Page 1)
• Items/Fields (Page 2)
• Additional Processing Code (Page 3)

Basic Information

Field Definitions

The first page of the “Edit Entity” ScreenMan form presents the basic information fields needed to set up and define the Entity.

REF: For a description of the fields on this screen see Table 105 and Section 17.2.3.2, “Search Criteria.”

                                EDIT ENTITY
NAME: ZZPATIENT                                                       PAGE 1 OF 3
-------------------------------------------------------------------------------

        NAME: ZZPATIENT
 DISPLAY NAME: TESTPATIENT

 DEFAULT FILE: 2

     SORT BY: B                              DATA MODEL:
   FILTER BY: ZZ                              READ ONLY:
       SCREEN:


                                                          QUERY ROUTINE:
   DESCRIPTION: +

_______________________________________________________________________________

EXIT     SAVE     NEXT PAGE     PREVIOUS PAGE     REFRESH    QUIT

ENTER A COMMAND, OR "^" FOLLOWED BY THE CAPTION OF A FIELD TO JUMP TO.

COMMAND:                                            PRESS <PF1>H FOR HELP  INSERT
	

NOTE: The READ ONLY field is not currently used.

Sample DESCRIPTION field text:

 1>THIS ENTITY CAN BE USED TO FIND TEST PATIENTS, USING THE B INDEX TO FIND
 2>LAST NAMES THAT START WITH "ZZ". THE ID ACTION WILL QUIT IF THE PATIENT
 3>IS NOT FLAGGED WITH THE TEST PATIENT INDICATOR.
 4>
 5>IT RETURNS BASIC DEMOGRAPHIC INFORMATION ABOUT EACH PATIENT. TO RUN IT
 6>FOR A SINGLE KNOWN TEST PATIENT, PASS THE PATIENT (#2) FILE IEN AS THE ID.
EDIT OPTION:
	

REF: For a description of the ENTITY (#1.5) file fields displayed on the “Edit Entity” Screen (Page 1), see Table 105.

Search Criteria Fields

An Entity can be used to return a list of records if the search criteria are defined:

     SORT BY: B                              DATA MODEL:
   FILTER BY: ZZ                              READ ONLY:
       SCREEN:

QUERY ROUTINE:
	

FIND^DIC Parameters

The following parameters can be defined to support a FIND^DIC call on the DEFAULT FILE NUMBER (#.02) field:

• Set the SORT BY parameter to the name of the index.
• Set the FILTER BY parameter to the search value.
• Optionally, define the SCREEN parameter (M code that sets $T).

In this example, the ZZPATIENT Entity searches the PATIENT (#2) file using the B index, looking for any name that starts with “ZZ”.

Advanced: To change the search value at runtime, set FILTER BY to the name of a local variable that contains the search value, such as DFN, which holds the current PATIENT (#2) file IEN.

If the search index is compound, then lookup values can also be provided at run time via the GET^DDE API for each subscript using the QUERY array.

Query Routine

Alternatively, you can write a special lookup routine called the Query Routine to perform the search. This routine must set the following array:

    DLIST(#)=ID

Where:

• # is a sequential number greater than Zero.
• ID is the record identifier (usually an IEN or IENS string) or input value.

REF: Table 108 lists the variables that are passed into the GET^DDE API or set by VA FileMan and can be referenced as read-only in the GET QUERY ROUTINE (#5) field.

Reviewed/Updated: May 2026