| Contents: | Main | Section | See Also: | User Manual | Advanced User Manual |
The second page of the “Edit Entity” ScreenMan form allows access to create and manage the list of property Items for the Entity.
EDIT ENTITY
NAME: ZZPATIENT PAGE 2 OF 3
-------------------------------------------------------------------------------
ITEM SEQ TYPE FIELD SUB/FILE
ADDRESS 7 C
ALIAS 4 L 2.01
CITY S .114 2
DATEENTERED 3 S .097 2
FLAG 5 F
NAME 2 S .01 2
PATIENTID 1 I
STATE S .115 2
STREET S .111 2
WHOENTERED 6 E .096 2
ZIP S .116 2
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
A SEQUENCE number (“Seq”; processing order) is generally assigned to each Item. If an Item has no SEQUENCE number, then it is skipped in the main processing loop. The result of each Item is returned in the local VALUE variable; tags are put around VALUE using the property name and added to the results string of the record.
An element ITEM TYPE (not the VA FileMan data type) is assigned to every Item. The ScreenMan editor pops up a dialog with fields appropriate for that ITEM TYPE:
Instead of returning a field value, the ID element automatically uses the current record identifier string as the return VALUE unless code in the Item's GET ACTION field sets the VALUE variable.
GET ACTION:
OUTPUT TRANSFORM: S VALUE=VALUE_";DPT("
INPUT TRANSFORM:
An optional OUTPUT TRANSFORM field can be defined to modify VALUE if any special formatting is needed.
NOTE: The INPUT TRANSFORM field is not currently in use.
FIXED RESPONSE: TEST PATIENT
GET ACTION:
The Fixed String element returns either of the following in VALUE:
This ITEM TYPE is useful for returning data that cannot be mapped to a single field. For example, a function can be called in GET ACTION that computes a value based on multiple fields or other data.
The Simple Field element uses a $$GET1^DIQ call to retrieve the specified field in the VALUE variable.
FIELD#: .01 FILE#: 2
EXT PTR LKUP:
INTERNAL VALUE:
GET ACTION:
OUTPUT TRANSFORM:
INPUT TRANSFORM:
The simplest form requires only a FILE# and FIELD#, returning the external form of the value. Other optional input parameters can be defined to modify the output.
For POINTER-type fields, the EXT PTR LKUP can contain a field number in the pointed-to file that should be returned instead of the usual NAME (#.01) field.
FIELD#: .115 FILE#: 2
EXT PTR LKUP: 1
INTERNAL VALUE:
Set the INTERNAL VALUE flag to YES to force the internal form of the field value to be returned; this is especially useful when some other transformation must be done to the data.
FIELD#: .097 FILE#: 2
EXT PTR LKUP:
INTERNAL VALUE: YES
GET ACTION:
OUTPUT TRANSFORM: S VALUE=$$FMTE^XLFDT(VALUE,5)
INPUT TRANSFORM:
An optional OUTPUT TRANSFORM field can be defined to modify VALUE (e.g., if the field returns a VA FileMan date it may need to be reformatted).
NOTE: The INPUT TRANSFORM field is not currently in use.
Alternatively, the GET ACTION field can execute M code that sets VALUE, or do any other pre-processing needed for this item. This code is executed first, and if VALUE is defined then no $$GET1^DIQ call is attempted.
REF: For a list of the variables available to reference in the GET ACTION field, see Table 107.
If a field from a related file or subfile needs to be retrieved, the FILE# can be changed for an Item. The record identifier will likely need to be changed as well, for that Item only. The DIEN variable holds the identifier for the record and should not be changed; the IEN variable is initialized to the value of DIEN and can be changed in the GET ACTION for a single Item.
FIELD#: .01 FILE#: 2.01
EXT PTR LKUP:
INTERNAL VALUE:
GET ACTION: S IEN="1,"_DIEN
The Word-Processing element returns a field value like a Simple Field but automatically converts the resulting VA FileMan word-processing array to a single return string.
FIELD#: 2 FILE#: 8925
EXT PTR LKUP:
WORD WRAP: MAXIMUM WORD SIZE:
WP ERROR MSG:
GET ACTION: D GET^ZZTEXT
If the GET ACTION field is used to execute custom M code to get the value, the text must be returned in the following array:
WP(#)=value or WP(#,0)=value
Where:
The DDE API concatenates the lines of text together into a single long text string.
If the WORD WRAP field is set to:
If the MAXIMUM WORD SIZE field:
The Entity element returns multiple data elements for a single field value. These are especially useful for creating a coded element from a POINTER, or for any group of data that will be re-used. Create the Entity to be embedded first or simply enter its name when editing this Item to create a stub (make sure to finish it later!).
FIELD#: .096 FILE#: 2
EXT PTR LKUP:
INTERNAL VALUE: YES
GET ACTION:
OUTPUT TRANSFORM:
INPUT TRANSFORM:
ENTITY: ZZUSER
The field's VALUE is first retrieved in the same manner as for a simple field, by executing the Item's GET ACTION code or $$GET1^DIQ according to the specified input parameters. The same modifications can be made to the VALUE for an Entity as with Simple Fields. The VALUE is then passed into the Item's Entity as its ID.
Nested Entities are especially useful for POINTER-type fields, to return multiple fields from the pointed-to file (e.g., IEN, NAME (#.01) field, etc.). Set the INTERNAL VALUE flag to YES to retain the POINTER for passing into the nested Entity as its ID.
The Complex Group element is a set of discrete fields in the DEFAULT FILE (not a subfile or separate file) that are returned together as a group.
To create a group:
The GET ACTION code field can be used for any needed pre-processing. For example, fields from the PATIENT (#2) file can be returned together in the Address group. After creating each Simple Field Item, collect the Items under Address in the desired SEQUENCE:
GET ACTION:
SEQ ITEM
1 STREET
2 CITY
3 STATE
4 ZIP
Note that the Street, City, State, and Zip Items have no SEQUENCE (Seq) value, as shown below:
ITEM SEQ TYPE FIELD SUB/FILE ADDRESS 7 C ALIAS 4 L 2.01 CITY S .114 2 DATEENTERED 3 S .097 2 FLAG 5 F NAME 2 S .01 2 PATIENTID 1 I STATE S .115 2 STREET S .111 2 WHOENTERED 6 E .096 2 ZIP S .116 2
The List element returns multiple results from a:
Each result in the list can be either a single value, or an Entity for complex or coded values.
Example of editing a Subfile List Item:
LIST TYPE: SUBFILE
GET ACTION:
SELECT THE ENTITY OR FIELD TO BE RETURNED FOR EACH RECORD:
ENTITY: ZZALIAS FIELD#:
EXT PTR:
INT VAL:
XML TAG: NAME
The GET ACTION field can execute M code that does any setup or pre-processing needed for this item.
The format of each result must be defined, either as input to a nested Entity or a Field number in the target sub/file; some field attributes can be defined as Simple Field Items.
The XML TAG specifies the tags to be used around each instance in the list when using XML. If this field is not defined, the name of the List Item is used. JSON does not put tags around each list item, so this value is ignored if using JSON.
Input parameters for a FIND^DIC lookup can be defined for File lists, in the same way as for the Entity's Search Criteria. Lookups for subfile lists use LIST^DIC instead and only support the Screen.
The dialog that pops up when the List Type is selected:
DEFINE THE SUB/FILE SEARCH FOR THE DESIRED RECORDS:
FILE#: 2.01
XREF:
FILTER BY:
SCREEN:
If each result in the list is returned as an Entity, a query can instead be defined for that Entity to determine the list contents.
A Complex Field List is simply a collection of specific field values returned as a list.
LIST TYPE: COMPLEX
GET ACTION:
SELECT THE ENTITY OR FIELD TO BE RETURNED FOR EACH RECORD:
ENTITY: FIELD#:
EXT PTR:
INT VAL:
XML TAG: ADDRESS
The GET ACTION field can execute M code that does any setup or pre-processing needed for this item.
The XML TAG specifies the tags to be used around each instance in the list when using XML. If this field is not defined, the name of the List Item is used. JSON does not put tags around each list item, so this value is ignored if using JSON.
The contents of the list are created in the same way as for Complex Groups.
NOTE: The only difference between a complex group and a complex list are the brackets used when returning the results as JSON.
When the List Type is selected, the screen dialog pops up allowing other Items from the Entity to be added to the list:
SELECT THE ENTITY ITEMS TO RETURN THE DESIRED VALUES FOR THIS LIST:
SEQ ITEM
1 PERMANENTADDRESS
2 TEMPORARYADDRESS
Because each Item has its own field definition, the Entity and Field attributes are not used for complex lists.
LIST TYPE: ARRAY
GET ACTION: N I S I=0 F S I=$O(VAEL(1,I)) Q:I<1 S DLIST(I)=+VAEL(1,I)
SELECT THE ENTITY OR FIELD TO BE RETURNED FOR EACH RECORD:
ENTITY: ZZZELIGIBILITY FIELD#:
EXT PTR:
INT VAL:
XML TAG: ELIGIBILITY
For Custom Lists, the GET ACTION code is used to generate the list instead of defining search criteria and must create the following array:
DLIST(#)=value
Where:
Each value can be either the actual result for that instance, or a string to pass into the Item's Entity as its identifier. The Field attribute is not used for custom lists.
The XML TAG specifies the tags to be used around each instance in the list when using XML. If this field is not defined, the name of the List Item is used. JSON does not put tags around each list item, so this value is ignored if using JSON.
The following variables can be referenced in the GET ACTION of a data element Item:
| Variable | Description |
|---|---|
| DFN | PATIENT (#2) file IEN. |
| DIEN | ID (IEN or ID string) of source data record being accessed. |
| FIELD | Field number of source data in FILE number for current Item. |
| FILE | File number of source data for current Item (can be different than the Default File Number for the Entity). |
| IEN | Same as DIEN, but can be changed for current Item if FILE is not the Default File Number. |
| ITM | DA of current Item in ITEM (#1.51) subfile. |
| ITM0 | Zero node of current Item. |
| TAG | Name of current Item; used for XML or JSON tags. |
| TYPE | Item Type name. |
| VALUE | Value or result of data element. |
Set DDEOUT=1 in GET ACTION to exit the Item without adding its value to the results.
Set DDEQUIT=1 in GET ACTION to exit the entire record without adding anything to the results.
Reviewed/Updated: May 2026