| Contents: | Main | Section | See Also: | User Manual | Advanced User Manual |
Table 105 lists the ENTITY (#1.5) file fields actively in use:
| Field | Description |
|---|---|
| NAME (#.01) | (Required) This field contains the name of the Entity. Each Entity must have a unique name. Since the ENTITY (#1.5) file is a shared public file, it is strongly recommended to begin the name with the VistA namespace of the owning package. |
| DEFAULT FILE NUMBER (#.02) | (Optional) This is the primary file or subfile number associated with this Entity, and the default source file for data. It is optional if no data associated with this Entity is stored in any VA FileMan file. It is recommended that you enter a VistA file number in this field, but it is not required. Fields mapped to the properties are assumed to be from the VistA file number referenced in this field unless otherwise specified. If data is being expanded instead of extracted, such as expanding a name string into its components, a source file is not needed. |
| SORT BY (#.03) | (Optional) This field contains the name of the cross-reference to use for the lookup. |
| FILTER BY (#.04) | (Optional) This field is the value, or the name of a local variable that contains the value, to filter entries by using the specified cross-reference. REF: For a list of variables that are available to use (read-only), see Table 108. |
| DATA MODEL (#.06) | (Optional) If this Entity is intended to return data according to the constraints of a specific data model (e.g., SDA or FHIR), then enter that target data model in this field. |
| DISPLAY NAME (#.1) | (Optional) This field is the name that is used for the XML or JSON tags (property names). If no value is entered here, the NAME (#.01) field is used. This field is used as the outer tags around each result and is usually the name of the class from the data model that is being mapped (e.g., SDA or FHIR). |
| ITEM (#1) Multiple | The Items Multiple defines the data elements that make up the Entity. REF: For a description of the subfields, see Table 106. |
| GET ENTRY ACTION (#2) | This field contains standard M code that does any set up needed to process the Entity. It is executed once when the Entity is first invoked, before the query is run and any records are processed. Additional local variables can be set that can be referenced throughout the Entity, but they must be cleaned up in the GET EXIT ACTION field. |
| GET EXIT ACTION (#3) | This field contains standard M code that does any clean up that is needed on a GET ENTRY ACTION; it is executed once at the end, after all records found by the query are processed. Any local variables created in the GET ENTRY ACTION or GET ID ACTION fields must be killed here. |
| GET ID ACTION (#4) | This field contains standard M code that is executed once for every record, before the data elements are retrieved. It can be used for any setup or validation that is needed for each record. The current record ID is available to reference as read-only in the local DIEN variable. If a record should not be included in the results, you can S DDEOUT=1 and processing quits without including the record. |
| GET QUERY ROUTINE (#5) | (Optional) This field is the tag^routine used for finding the appropriate records in the VistA primary source file, instead of FIND^DIC. This routine creates the array DLIST(#)=ID, where # is a sequential number and ID is a string that identifies a record in the Default File. ID can also be a string that is processed by this entity. REF: For a definition of local variables that can be referenced and used (not changed or killed), see Table 107. |
| SCREEN (#5.1) | (Optional) This field contains standard M code that sets DIC('S') for a screen, which is used in a FIND^DIC query. |
| DESCRIPTION (#19) | (Optional) This is a description of the Entity, which is used to document its intended usage, expected input values or data sources, and any other information that is helpful for maintenance. It is strongly recommended that you enter a description of the Entity in this field. |
| GET POLICY (#19.1) | (Optional) This field points to the APPLICATION ACTION (#1.61) file entry, which links a Data Access Control POLICY (#1.6) file entry to a GET request for this Entity, to determine if a user or client is authorized to access this data. |
Table 106 lists the ENTITY (#1.5) file ITEM (#1.51) Multiple subfields:
| ITEM (#1) Multiple Subfield | Description |
|---|---|
| ITEM (#.01) | This field contains the name of the Item that is used as the XML or JSON tag. |
| SEQUENCE (#.02) | This field defines the sequence in which to process top-level items. Leave this field blank for Items that will be processed via the Complex Fields group. |
| ITEM TYPE (#.03) | This field contains the type of element for this Item. It describes how to find the source data in VistA, as well as its structure in the XML or JSON results:
|
| FILE NUMBER (#.04) | This field contains the VistA file or subfile number containing the data value(s) for this Item. |
| FIELD NUMBER (#.05) | This field contains the number of a field in the file that is the source of the data for this Item. |
| EXTENDED POINTER LKUP (#.06) | This field contains the number of a field in the pointed-to file to return as the resolved external value, instead of the .01 field. |
| RETURN INTERNAL VALUE (#.07) | If this field is set to YES, the value of this Item should remain in internal format. The default is NO, which returns the external format. |
| ENTITY (#.08) | This field contains the name of an Entity whose value should be constructed and returned as the value for this Item. A parent or ancestor of this Entity cannot be used as a descendant item. |
| WORD WRAP (#.09) | If this field is set to YES, the text is returned without carriage returns (CR) or line feeds (LF) so the client can allow the text to wrap. The default is NO, which inserts CR-LF characters between lines. |
| MAXIMUM WORD SIZE (#.1) | This field contains the maximum number of characters that a WORD PROCESSING field can return. If the field value exceeds this limit, the text in the WORD ERROR MESSAGE (#.11) field is returned instead of the value. |
| WORD ERROR MESSAGE (#.11) | This field contains an error message that is returned if a WORD PROCESSING field value exceeds the number of characters defined by the MAXIMUM WORD SIZE (#.1) field. |
| LIST TYPE (#1.01) | This field contains the source of this Item's values, if the list instances come from a file, sub-file, Complex Fields group, or an array created by the GET ACTION logic. |
| XML NAME (#1.02) | This field contains the name to be used for the tags around this Item when returning XML, for each entry in the list. If this Item is an Entity, its Display Name is the default, but this name overrides it if defined. |
| XREF (#1.03) | If this list is coming from a file, use this field to enter the cross-reference to be used to find the desired records. |
| FILTER BY (#1.04) | If this list is coming from a file, you can enter the name of a local variable in this field that contains the value to filter entries by using the specified cross-reference. REF: For a list of variables that are available to use (read only), see Table 108. Other variables can be created in the GET ACTION code field; these should be killed in the Entity's GET EXIT ACTION. |
| SCREEN (#1.1) | This field contains standard M code that should set DIC('S') for a screen. |
| FIXED RESPONSE (#2) | Use this field to add static text that should always be returned as the value of this Item. |
| COMPLEX TYPE (#3) Multiple | This field allows an Item to return a group of fields or data elements. |
| OUTPUT TRANSFORM (#4) | This field contains code that is executed after extracting the data value, which can be used to re-format it for XML or JSON. It expects the VALUE variable to contain the current form of this property's value and should leave VALUE set to the desired form (e.g., S VALUE=+VALUE). If the value should be omitted, set the VALUE variable to NULL. |
| GET ACTION (#6) | This field contains code that is executed when extracting this item from VistA. It can do additional setup tasks for non-simple elements or even create the return value itself for simple fields that cannot be pulled directly from VistA. At the time this code is executed within ^DDE, the VALUE variable can be returned as the value of this property. If VALUE is not set here, then $$GET1^DIQ is called using the Item's properties to determine a value. If a value for this Item cannot or should not be returned, set DDEOUT=1 to cause ^DDE to quit the item and go on to the next one. REF: For a list of variables that can be referenced, see Table 107. |
Reviewed/Updated: May 2026