Setting Up a Virtual Entity Using the Wizard

After reviewing the data requirements for a virtual entity (see Understanding the Virtual Entity Data Requirements), follow these steps to create a virtual entity using the wizard:

1. Open or create a view of the Entities service.
2. Click the Virtual Entity Wizard icon in the view toolbar to launch the wizard.
   
   
3. Review the wizard's introductory screen and click Next to continue.
   
   
    
4. Select the database that contains the data to be accessed by the virtual entity and click Next to continue. In the example shown in the figure below, this is the VirtualData database.
   • If the data is stored locally on the APTIFY database, select APTIFY from the drop-down list.
   • If the data is stored locally on a database other than APTIFY, select that database from the drop-down list.
   • If the data is not stored locally, select the database that contains the view you created from the drop-down list. See Creating a View in a Local Database to Point to a Virtual Entity Data Source more information.
     
     
5. Select the table or view from which the virtual entity will retrieve its data.
   • If the data is stored in the APTIFY database, select the view or table that will act as the data source for the virtual entity.
   • If the data is stored locally in a non-APTIFY database, select the view or table that will act as the data source for the virtual entity.
   • If the data is not stored locally, select the view you created for the virtual entity. See Creating a View in a Local Database to Point to a Virtual Entity Data Source for more information.
   • In the example below, the virtual entity will use the vwLibraryInventory view as its data source.
     
     
6. Select the integer-type field from the table or view that will act as the primary key for the virtual entity.
   • If the source data has an ID field, use the ID field. Otherwise, select a unique, integer-type field that the wizard will alias as the virtual entity's ID field.
   • In the example the figure below, the vwLibraryInventory view has a BookID field that will be aliased as the ID field.
     
     
     
     
7. Click Next to continue.
   
   
8. Edit the entity fields as necessary and click Next to continue.
   • Name: Modify the virtual entity's Name, as necessary. If creating a virtual entity of Aptify data, you must assign the virtual entity a unique name. For example, if creating a virtual entity of the ProductPrices entity, use a name like VirtualProductPrices.
     
     
   • Display Name: This is the name that is displayed for this entity within the Aptify graphical user interface.
     
     
   • Base View: The Virtual Entity wizard automatically creates a base view for the entity. Modify the base view name as necessary. If creating a virtual entity of APTIFY data, you must assign the virtual entity a unique base view name. For example, if creating a virtual entity of the ProductPrices entity, use a base view name like vwVirtualProductPrices. The Base View's name must be unique or the virtual entity will not be saved.
     
     
   • spGetRecord: The Virtual Entity wizard automatically creates a Get record stored procedure for the entity. Modify the stored procedure's name as necessary. If creating a virtual entity of APTIFY data, you must assign the database object a unique name. For example, if creating a virtual entity of the ProductPrices entity, use a stored procedure name like spGetVirtualProductPrices. The spGetRecord's name must be unique or the virtual entity will not be saved.
     
     
   • Base Database: Specify the database where the virtual entity information should be stored. Typically this is the APTIFY database but you could specify a different database on the same server if necessary.
     
     
   • Description: Enter a description for the virtual entity.
     
     
     
     
9. Leave the Display the new virtual entity definition after creating box selected and click Finish to create the virtual entity.
   
   
   
   • The virtual entity's Entities record opens after the wizard has successfully created it. See About the Virtual Entity Characteristics for information on the layout of a virtual entity.
   • If the wizard encounters a problems, an error message will appear. In this case, follow these steps:
   1. 1. Close the wizard and select the Session Exception viewer to determine the cause of the error.
      2. Resolve the issue that caused the wizard to fail.
      3. Search the Database Objects service to determine if the wizard created the Base View and/or spGetRecord stored procedure for your virtual entity. If so, delete these database objects.
      4. Re-run the Virtual Entity wizard.
         
         
10. In the virtual entity's Entities record, click the Security tab and assign Read access to the groups and individual users who should have access to this virtual entity.
    • Virtual entities provide read-only access to data. Therefore, only select the Read option when assigning User or Group Permissions.
      
      
11. Click the Applications tab and add the virtual entity to one or more applications.
    
    
12. If the virtual entity links to one or more entities in Aptify, you can configure the virtual entity to open an Aptify record in the corresponding service when a user attempts to open a row in a virtual entity's view. To enable this feature, you need to add the appropriate entity attributes and a viewer plug-in to the virtual entity, as described below.
    
    • Entity Attributes: Click the Configuration > Attributes tab and add the appropriate attributes listed below to define which Aptify record should be opened if a user attempts to open a virtual entity record.
      • DisplayFormRedirectEntity: Identifies the type of Aptify entity record to open when a user attempts to open a record in a virtual entity. This attributes should be used when the virtual entity is linked to only one entity in Aptify.
        
        
      • DisplayFormRedirectIDField: Identifies the field in the virtual entity that links to the ID field of the Aptify entity specified in the DisplayFormRedirectEntity attribute. If this attributes is not specified or blank, the value ID will be assumed.
        
        
      • DisplayFormRedirectEntityField: Identifies the name of the field in the virtual entity that defines the Aptify entity. This attribute should be used when the virtual entity is linked to multiple entities within Aptify.
        
        
      • DisplayFormRedirectEntityFieldType: Identifies whether the entity identifier provided in the DisplayFormRedirectEntityField represents an entity ID or entity Name. ID and Name are the supported values for this attribute.
        
        
      • DisplayFormRedirectEntityIDOffsets: If your virtual entity uses an offset to ensure unique IDs for links to multiple Aptify entities, this attribute is a comma delimited list of entities and ID offset values in the format of [Entity Name]=[Offset Value], [2nd Entity Name]=[Offset Value]. When specified, the ID of the Virtual Entity record will be used to determine which entity to display.
        
        
    • The figure below is an example of a virtual entity linked to one entity in Aptify. If the Virtual Library Inventory entity specifies an AuthorID field that corresponds to a Persons.ID in Aptify, then with the attributes defined below, Aptify would open the Persons record that corresponds to the book's author when a user double-clicks an entry in the virtual entity's view.
      
      
    • The example in the figure below is a virtual entity created to combine the Aptify entities Companies and Organizations into a single view, A field called Entity is used to identify which entity should be used when the row is selected. To ensure a unique ID between the Companies and Organizations records returned, an offset has been used. 10 million (10,000,000) has been added to the ID of each of the Companies records and 20 million (20,000,000) has been added to the ID of each of the Organizations records. In this case, the DisplayFormRedirectEntityIDOffsets attribute can be used. Based on the attributes defined below, Aptify would open either the corresponding Companies or Organizations record depending on the row the user selects in the virtual entity's view.
      
      
    • Viewer Plug-In: If you defined the DisplayFormRedirect attributes, you also need to add the Entity Redirect Viewer Plug-In object to the virtual entity. Follow these steps:
    1. 1. Click the Plug-Ins tab and open a new Plug-Ins record.
       2. Select Viewer as the Plug In Type.
       3. Enter DataModules.EntityRedirectViewerPlugIn in the Object Name field.
       4. Enter EntityRedirectViewerPlugIn in the Assembly Name field.
       5. Enter Aptify.Framework.WindowsControls.EntityRedirectViewerPlugIn in the Class Name field.
          
          
       6. Click OK to save and close the Plug Ins record.
          
          
13. If necessary, click the Fields tab and modify the Default In View option for the virtual entity's fields as needed.
    • By default, all fields have the Default In View option enabled. You may want to disable this option for one or more fields.
      
      
14. Save and close the Entities record.
15. Create views of the virtual data as needed. See About the Virtual Entity Characteristics for more information.