The entity packing and unpacking wizards assist with moving entities from one location to another. The Entity Unpacker is typically used to unpack entities during the initial server installation process, or during a server upgrade to a new version of Aptify. The Entity Packer and Entity Unpacker can also be used to move customized entities from one server to another. For example, to move new entities from a development server to the production server, the entities are packed on the development server and then unpacked on the production server.
Note that to successfully pack and unpack entities, the user running these wizards should be a member of the computer's local Administrators group.
This section covers the following topics:
Packing Entities
The process of packing entities involves gathering all the necessary information pertaining to the entity and storing the data in a form that allows the entities to be installed at another location. Everything required for the entity installation is packed into a folder with the entity name and the extension .entpak and is placed in the location specified during the packing process. For example, a packed SampleServices entity is stored with the filename, SampleServices.entpak.
In many cases, an entity may have multiple dependent entities that also need to be packed in order for the entity to function correctly in the new location. When you create an entity pack, you can choose to also pack dependent entities. However, the time necessary to pack the entity is increased with each dependency (and the dependencies of those entities as well). For example, if the Persons entity needs to be packed, all dependent entities associated with the Persons record are also packed, including Companies, Member Types, Member Status Types, Organizations, and others. Once all the dependencies for the Persons entity are packed, all the dependencies for Companies, Member Types, and so forth are also packed. This has the potential to become a time-intensive process. In order to reduce the amount of time it takes to pack a particular entity; you can copy any existing dependent packed entities into the destination folder. Only those dependent entities which have not been changed since the date they were last packed should be copied to the destination folder.
For example, if packing the Persons entity with dependencies, the user can copy an existing Companies.entpak folder into the destination folder for the packed entities. During the packing process, Aptify detects that Companies.entpak already exists in the folder and does not attempt to repack that entity or any dependencies associated with that entity. If the above steps are not followed, all dependencies for the selected entities are packed and saved in the destination folder.
In other instances, the user may want to pack an entity along with all of its dependencies. This may occur if the target entity relies on changes that have been made to the dependent entities. If this is the case, simply mark the main entity, enable the pack dependencies options, and do not copy any .entpak folders to the destination folder. This ensures that the system automatically packs the main entity and all the dependent entities to the destination folder.
By default, users and groups that exist on the source server are packed when packing an entity. However, there may be cases when unpacking users on the target server may not be appropriate, especially when the entities are created in a development environment and then unpacked on a production server. With this in mind, the entity packing process includes the ability for a user to specify which users and groups to include in a packed entity. In addition, an administrator can also select which sub-type entities to pack (with or without the sub-type's parent entity) and whether or not to pack the sub-type entity's associated users, groups and sub-types which can greatly reduce the amount of time necessary to pack a particular entity.
Follow these steps to pack an entity:
- Launch the Entity Packer from the Entities service.
- The Pack Entities icon appears in the service toolbar or view toolbar for the Entities service.
- The Pack Entities icon appears in the service toolbar or view toolbar for the Entities service.
- Browse to the network location where you want to save the packed entities in the Packing Directory drop-down.
- Click Create Dir if you want to create a new sub-folder in a selected network location.
- Modify the packing options, as necessary.
- When the Pack Dependent Entities option is selected, the wizard packs the selected entities and all other entities that are dependent upon the selected entities and the entities that are dependent upon those dependencies.
-
- This ensures that all of the necessary entities are packed so that your selected entities will function properly on a new system. However, note that this can be time-consuming if the selected entities have a large number of dependencies (and if those dependencies have their own dependencies).
- In order to reduce the amount of time it takes to pack a particular entity, you can copy existing, dependent packed entities directly into the destination folder. (Assuming that you have made no changes to the entity since it was originally packed).
- When Pack Dependent Database Objects option is selected, the wizard packs all of the entity's non-generated database objects, including stored procedures (listed under the Stored Proc. tab), the entity's Base View, and all database objects listed under the entity's DB Objects tab.
- Select Next.
- Select the Pack column for each entity that you want to include in the entity pack.
- By default, all entities listed in the view from which you launched the wizard are selected.
- Click Check All to select all of the entities for packing.
- Click Uncheck All to remove the selection from all selected entities. Clears the Pack Form Templates and Pack Process Flows columns check boxes.
- For all of the entities that you want to pack, select or clear the Pack Form Templates and Pack Process Flows columns check boxes, as necessary.
- When the Pack Form Templates check box is selected for a particular entity, the wizard packs all non-generated form templates associated with the entity.
-
- Note that the wizard does not pack generated forms since the target system will generate them automatically during the unpacking process.
- If the wizard packs any form templates, it adds this information to a FormTemplates.recpak sub-folder in the entity's entpak folder. The recpak folder is a data pack folder that contains record information for the form template and its associated records (such as Form Template Parts records). See Data Packing and Unpacking for information on the contents of the recpak folder.
- Note that the wizard does not pack generated forms since the target system will generate them automatically during the unpacking process.
- When the Pack Process Flows box is selected for a particular entity, the wizard packs any Event Handlers and corresponding Process Flows associated with the entity.
-
- If the wizard packs any Event Handlers and Process Flows, it adds this information to an EventHandlers.recpak sub-folder in the entity's entpak folder. The recpak folder is a data pack folder that contains record information for the event handler and its associated records (including the corresponding Process Flow). See Using the Data Packing and Unpacking Wizards for information on the contents of the recpak folder.
- If the wizard packs any Event Handlers and Process Flows, it adds this information to an EventHandlers.recpak sub-folder in the entity's entpak folder. The recpak folder is a data pack folder that contains record information for the event handler and its associated records (including the corresponding Process Flow). See Using the Data Packing and Unpacking Wizards for information on the contents of the recpak folder.
- Select Next.
- Specify which Users records, Groups records and sub-type entities to include in the pack.
- Selecting the All Users options packs all Users records associated with the selected entities and/or sub-types.
- Selecting the All Groups option packs all Groups records associated with the selected entities and/or sub-types.
- Selecting the All Sub Types option packs all sub-type entities associated with selected entities.
- Click Finish to pack the selected entities (and the dependent entities and/or database objects, as applicable).
- The Entity Packer wizard includes a status bar at the bottom of the dialog (as shown below) to visibly display the progression of the packing process. Once the wizard is complete, a message displays that the process is complete.
- The Entity Packer wizard includes a status bar at the bottom of the dialog (as shown below) to visibly display the progression of the packing process. Once the wizard is complete, a message displays that the process is complete.
It is important to keep in mind that when an entity is unpacked, all changes made to that entity are included, regardless of the readiness of those changes for testing or production.
Entity Pack Structure
Each top-level entity pack (.entpak) folder contains the following sub-folder(s) and files:
- DBObjects folder: If you select Pack Dependent Database Objects, the wizard stores any non-generated database objects associated with the entity in this folder.
- FormTemplates.recpak folder: If you select Pack Form Templates, the wizard stores the entity's non-generated form templates and related records in this folder (which is a data pack, see Using the Data Packing and Unpacking Wizards).
- EventHandlers.recpak folder: If you select Pack Process Flows, the wizard stores any Event Handlers linked to the entity and their associated Process Flows in this folder (which is a data pack, see Using the Data Packing and Unpacking Wizards).
- LinkedFieldData.recpak folder: All relevant records associated with this entity (such as the Groups and Users who have been granted permissions on the entity's Security tab) are stored in this folder (which is a data pack, see Using the Data Packing and Unpacking Wizards).
- Objects folder: This folder stores any Object Repository Objects associated with this entity.
- Subtype entpak folder(s): If the entity has one or more sub-types, each sub-type has its own entity pack (entpak) sub-folder.
- ENTITY.APT file: This file stores information about the entity in XML format. The unpacker wizard uses the information in this file to install the entity on the target server.
Unpacking Entities
Unpacking entities imports packed entities to another Aptify system. Note that Aptify recommends backing up the destination server before starting the unpacking process.
Follow these steps to pack an entity:
- Launch the Entity Unpacker from the Entities service.
- The Install Entities... icon appears in the service toolbar or view toolbar for the Entities service.
-
- Non-admin users cannot run the Install Entities wizard.
- Non-admin users cannot run the Install Entities wizard.
- On the first page of the Aptify Install wizard, select APTIFY from the Select the Entity Definitions Database list. Click Next.
- Select the appropriate database from the Select the Base Database for the Entities list. Typically, this is APTIFY. However, you can enter a custom database as necessary (depending on the design of your Aptify installation). Click Next.
- Browse to the directory where the entity pack(s) are located. Click Next.
- Select the entity or entities that you want to unpack, and then click Next.
- Select the Un-Pack column for each entity that you want to unpack. Clear the option from any entity that you do not want to unpack.
- By default, all entities in the selected folder are selected.
- Click Check All to select all of the entities for packing.
- Click Uncheck All to clear the check mark from all selected entities.
- By default, the Aptify Install wizard determines if any of the existing entities match one of the entities you are attempting to unpack. If an entity already exists, the wizard updates the entity using the information in the entity pack. If you do not want to update an existing entity to the version in the entity pack, clear the Upgrade Existing Entities option.
- Note that when Upgrade Existing Entities is selected, the Aptify Install wizard does not completely overwrite an existing entity; it compares the existing entity and the packed entity and does not overwrite typical client configurations made to the existing entity. For example, the wizard will add a new field to an entity, but it will not change the Display Name of an existing field, even if the entity pack contains a different Display Name.
-
- Specifically, the unpacking process will not modify the following data for fields in an existing entity: Description, DisplayName, DefaultValue, and SQLFieldSize.
- Specifically, the unpacking process will not modify the following data for fields in an existing entity: Description, DisplayName, DefaultValue, and SQLFieldSize.
- Click Finish. A message is displayed when the entities have unpacked successfully.
- The Aptify Install wizard unpacks the selected entities and all of the associated objects, form templates, and event handler data stored within the entity pack.
- Confirm that the unpacked entities appear as records in the Entities service. Also, confirm that any associated form templates, event handlers, and process flows were successfully added to their respective services.
Note Concerning Updating Existing Entities When a Field's SQL Size or Type Has Been Modified
Aptify uses the following criteria when a field's type or SQL field size no longer matches the field for the existing entity on the destination server:
- If the SQL field size of the field in the packed entity is greater than the existing field's size, the existing field's size will be updated.
- If the SQL field size of the field in the packed entity is less than the existing field's size, the existing field's size will not be updated.
- The field type of the field in the existing entity will not be updated, only the size of the field. For example, if the field in the packed entity is of field type and size nchar(15) and the same field in the existing entity is of field type and size nvarchar(10), the field in the existing entity will be updated to nvarchar(15).
- If a field in the existing entity is deleted before unpacking an entity that includes the field, the deleted field will be added back to the existing entity.
- If a field in the packed entity does not exist in the existing entity, the unpacking process will add the field to the entity. The unpacking process will not modify the following data for fields in an existing entity: Description, Display Name, or Default Value.
Comments
Please sign in to leave a comment.