Packaging Rules

The Packaging process requires numerous rules and logic to determine how the individual elements in applications and questionnaires are migrated from 1 instance of Archer to another. Packaging does not delete objects or permission settings. It only adds new or adds new and updates existing objects and permission settings. Exceptions include layout and advanced workflow, in which packaging replaces the existing settings.

After a package install, it is recommended to re-install the package until the number of warnings, errors, or both, are at a static state.

The following sections provide additional rules and logic.

Access roles

When you import access roles with groups during the packaging process, the groups are created without any members in the target instance. After the access roles are transported from the source instance to the target instance, you must manually add users to each group.

The following table describes the different results when you import access roles that are and are not linked to groups, depending on your target instance.

	Package Contains Access Role Not Linked to a Group	Package Contains Access Role that is Linked to a Group
Target contains access role only	Access role is updated, no group changes	Access role is updated, group is added and linked in target
Target contains group only	Access role is created, no group changes	Access role is created, group is linked to access role in target
Target contains unlinked access role and group	Access role is updated, no group changes	Access role is updated, group is linked to access role in target
Target contains linked access role and group	Access role is updated, no group changes (group remains linked to access role)	Access role is updated, no group changes (group remains linked to access role) Note: If the package and target linked groups are not the same, the access role is linked to both groups.

Advanced workflow

Packaging rules related to advanced workflow include:

• You cannot generate a package that contains an application or questionnaire with an advanced workflow if the Advanced Workflow Service is not running.

• If you install an application or questionnaire with an advanced workflow and the target application or questionnaire has active advanced workflow jobs (or active advanced workflow jobs for the applicable level in a leveled application) that are using a different version of the workflow, the updated workflow can have unpredictable effects on the active job(s) or might cause them to fail. It is recommended that you review the changes in the workflow and consider the implications those changes can have on active jobs. If you choose to install the updated workflow, review the active jobs and update them as necessary.

• All advanced workflows are installed as inactive. After installation, review the install logs for any errors and verify that the advanced workflow is configured correctly. After validating the advanced workflow, activate the workflow.

• If a package includes an advanced workflow, the following scenarios and behaviors apply.

  The following table describes the scenarios and behaviors.

  Target Application	Install Method	Install Option	Target Result
  No advanced workflow exists	Create New Only	Override Layout	Advanced workflow is created. New layouts are created. Existing layouts (matched by system ID) are updated. New data driven events are created. Existing data driven events are not updated.
  		Do Not Override Layout	Advanced workflow is created. New layouts are created. Existing layouts (matched by system ID) are not updated. New data driven events are created. Existing data driven events are not updated.
  	Create New & Update	Override Layout	Advanced workflow is created. New layouts are created. Existing layouts (matched by system ID) are updated. New data driven events are created. Existing data driven events are updated.
  		Do Not Override Layout	Advanced workflow is created. New layouts are created. Existing layouts (matched by system ID) are not updated. If you choose not to override the layout, you may need to make some manual updates to your existing layout so that it works with the advanced workflow. New data driven events are created. Existing data driven events are updated.
  Advanced workflow exists	Create New Only	Override Layout	Advanced workflow is not installed. New layouts are created, but not associated with the existing advanced workflow. Existing layouts are updated, but not removed from any existing workflow nodes. New data driven events are created. Existing data driven events are not updated.
  		Do Not Override Layout	Advanced workflow is not installed. New layouts are created, but not associated with the existing advanced workflow. Existing layouts are not updated. New data driven events are created. Existing data driven events are not updated.
  	Create New & Update	Override Layout	Existing advanced workflow is replaced with the advanced workflow in the package. New layouts are created and associated with the advanced workflow as applicable. Existing layouts (matched by system ID) are updated but disassociated from workflow nodes. The existing layouts are still available and can be reapplied to a workflow node, but the workflow may require manual configuration to work correctly with the existing layout. New data driven events are created. Existing data driven events are updated.
  		Do Not Override Layout	Existing advanced workflow is replaced with the advanced workflow in the package. New layouts are created and associated with the advanced workflow as applicable. Existing layouts (matched by system ID) are not updated. Any existing layout that does not exist in the package is disassociated from the workflow. The layout remains available and can be reapplied to a workflow node, but the workflow may require manual configuration to work correctly with the existing layout. New data driven events are created. Existing data driven events are updated.

• If the package does not include an advanced workflow, the package installation does not delete or modify any existing advanced workflow settings in the target instance.

Audit fields

Packaging rules related to audit fields include:

• The Created By and Last Updated values for all elements created during the package installation are attributed to the user who installed the package.

• The Last Updated value for all elements that are updated during the package installation are attributed to the user who installed the package.

Bulk actions

Packaging rules related to bulk actions include:

• All schedules are installed as inactive. After installation, review the install logs for any errors and verify that the schedule is configured correctly. Once you have validated the configuration, activate the schedule.

• If the Schedule Owner or Run As user for the schedule in the source instance does not exist in the target instance, the field is left blank and a warning is logged.

  Note: A system administrator, configuration administrator, or schedule owner must update these fields in the schedule.

• Linked actions are handled as follows:

  • If the Install Method is set to Create New and Update, new actions are created and existing actions are updated.

  • If the Install Method is Create New Only, only new actions are created. Existing actions are not updated.

• If the package contains an invalid configuration, a warning message is written to the package installation log and the schedule is saved as inactive. Validate the configuration, and then activate it.

Calculations

The calculation order is retained from the source to the target. This rule is also true for calculation order that can affect data driven events.

Calculated cross-references

Packaging does not allow you to update an existing cross-reference field to a calculated cross-reference field, and vice versa.

Data driven events

Packaging rules related to data driven events include:

• All rules in the package are installed regardless of association with any actions.

• All actions in the package are installed regardless of association with any rules.

• Existing rules and actions are not deleted by the package installation.

• Rule order is retained from the source to the target. This rule is also true for calculation order that can affect data driven events.

• If the package disassociates a link between a rule and an action, the association also is removed in the target instance.

• Rules related to Apply Conditional Layout actions include:

  • If you select the Override Layout option when installing a package, and the target instance includes Apply Conditional Layout actions that have different objects than specified in the package, the package installation removes the settings for the layout objects that are not applicable to the Apply Conditional Layout actions.

  • If you select the Do not Override Layout option when installing a package, and the package includes Apply Conditional Layout actions that assume a new layout is applied, the package installation removes the settings for the layout objects that are no longer applicable.

Default value

Packaging rules for default values abide by the following if a new field is created with a default value, or if a default value is added to an existing field, the existing content in the target instance is not updated with the default value.

Documentation attachments

Packaging rules related to documentation attachments include:

• Packaging includes attachment files for objects that include a documentation attachment attribute in the configuration. These include:

  • Solutions documentation

  • Applications documentation

  • Questionnaires documentation

  • Workspaces documentation

  • Dashboards documentation

  • Mail Merge templates report template

• The user who installed the package is listed as the creator for the attachments.

• Existing file attachments are not deleted during the installation process.

• Attachments in the package are not matched but added to the target instance. If the attachment already exists in the target instance, a duplicate attachment is created.

External Fields

To communicate with external data sources using Data Gateway, you must map external data sources to the Archer servers after package installation.

Note: Data Gateway is available through Professional Services engagement.

With existing applications, the external fields do not need to be updated.

With new applications, the external fields must be mapped.

These are the fields currently supported:

• Text

• Numeric

• IPv4

• IPv6

• Date

• Date with time

Fields

Packaging rules related to fields include:

• All attributes of fields can be updated by the package installation, with the following exceptions:

  • Type

  • Created By

  • Key Field Designation

  • Related Module

  • Associated Values List

• An existing private field is not changed to a public field.

Filter criteria

Packaging rules for Filter Criteria include the following attributes that are updated during installation:

• Values. If the system cannot map a Values List Value in the target instance, that item is removed from the Values field for the condition.

• Field to Evaluate. If the system cannot map the field in the target instance, the condition is migrated as a null condition.

• Condition Order Number

• Operator

• Relationship

• Advanced Operator Logic

Key fields

Packaging rules for Key Fields abide by the condition if the key field in the package is different from the key field in the target instance, the target instance retains the same key field attribute as before the installation.

Layouts

Packaging rules related to layouts include:

• The package installation process attempts to match all layouts in the package by system ID. The process ignores any layouts that do not match.

• You cannot map the default layout or map custom layouts to the default layout.

• You can map custom layouts to custom layouts (if they are not matched by system ID).

• If a layout is matched by system ID, you can map all layout objects on the matched layout.

Levels in applications

Packaging rules related to levels in applications include:

• Existing levels are not deleted by the package installation.

• The package installation cannot change a leveled application to a flat application.

• If the levels in the target instance are arranged in a different hierarchy than the levels in the package, the installation fails.

Personal reports

Packaging rules for Personal Reports do no install personal reports in the package installation. To include personal reports, promote the report to a global report before creating the package in the source instance.

Record permissions

Packaging rules related to record permissions include:

• User/Groups field population can be added to Record Permissions fields, but existing ones are not removed by the package installation.

• New inherited fields can be added, but existing ones are not removed by the package installation.

• If a User/Groups field in the target instance is configured as a Record Permissions field in the package, the package installation changes the field to the record permissions type.

Status fields

Packaging rules related to status fields include:

• If an existing application or questionnaire is updated, the current status in the target instance is not changed by the package installation.

• If the package creates a new application or questionnaire and there are not enough licenses, the new application or questionnaire is set to the Development status and a warning is logged.

Trending charts

You can add trending objects (fields and charts) to packages for migrating them to a target instance. Certain rules apply when packaging trending objects. The main rule is if the trended field is not added to the package, the layout object cannot be added to the package.

Archer uses the following rules when mapping trending objects, which are explained in the following sections.

Trending rules - trending enabled

The following table describes the trending rules when trending is enabled.

Source	Target	Install Method	Layout	Target Result
Yes	Yes	Create New and Update	Any	Trending enabled.
Yes	No	Create New and Update	Any	Trending enabled.
Yes	No	Create New Only	Any	Target field is not updated.
No	Yes	Create New and Update	Any	Trending enabled.
No	Yes	Create New Only	Any	Target field is not updated.

Trending rules - duration period

The following table describes the trending rules related to the duration period.

Source	Target	Install Method	Layout	Target Result
Same as Target	Same as Source	Create New and Update	Any	No change; remains the same.
Shorter than Target	Longer than Source	Create New and Update	Any	Retains the duration period specified in the Target.
Longer than Target	Shorter than Source	Create New and Update	Any	Retains the duration period specified in the Source.

Trending rules - referenced field

The following table demonstrates what occurs when:

• Trending is enabled or disabled for the field.
• Trended field is deleted.

Source	Target	Install Method	Layout	Target Result
Trending enabled	Trending enabled	Create New Only	Do Not Override Layout	Neither field is updated.
Trending enabled	Field different than the field from the Source instance.	Create New and Update	Do Not Override Layout	Target instance is updated to reference the field from the Source instance.
Trending enabled	Field different than the field from the Source instance.	Create New Only	Do Not Override Layout	Field exists in both places. The chart object is updated to reference the field in the Source instance.
Trending enabled	Field different than the field from the Source instance.	Create New Only	Do Not Override Layout	Field does not exist in the Target instance. The field from the Source instance is created in the Target instance, and then referenced by the trending chart object in the Target instance.
Trending enabled	Trending enabled	Create New and Update	Do Not Override Layout	Target instance is updated with any trending chart properties that exist in the Source instance. The layout is not affected.
Trending enabled	Trending enabled	Create New and Update	Override Field	Target instance is updated with any trending chart properties that exist in the source. The position of the trending chart object on the application layout and the span properties are affected.
Trending enabled	Trending enabled	Create New Only	Override Layout	Position of the trending chart object on the application layout is affected. The field and trending chart object properties are not updated.
Trending enabled	Trending disabled	Create New Only	Override Layout	The following message displays: Package Install Successful. The trending chart cannot be created in the Target instance for the following reasons: Referenced field is not trended. The packaging operation does not enable trending in the Target instance when Create New Only is selected.
Trending enabled	Trending disabled	Create New and Update	Override Layout	Trending chart object and referenced field are created in the Target instance. Application layout matches the Source instance. Field in the Target instance is trending-enabled, and the associated trending chart is created in the Target instance.
Trending enabled	Field deleted	Create New Only	Do Not Override Layout	Trending chart object and referenced field are created in the Target instance. Application layout is not overridden.
Trending enabled	Field deleted	Create New and Update	Do Not Override Layout	Trending chart object and referenced field are created in the target. Application layout is not overridden.

Trending rules - trending chart objects

The following table demonstrates what occurs when the trending object (field or chart) or placeholder object is added to the layout.

Source	Target	Install Method	Layout	Target Result
Trending object on layout	Trending object on layout	Create New Only	Do Not Override Layout	Neither field is updated.
Trending object on layout	Trending object on layout	Create New and Update	Do Not Override Layout	Target instance is updated to reference the field from the Source instance.
Trending object on layout	Trending object on layout	Create New Only	Do Not Override Layout	Referenced field exists in both places and maps. The trending object is updated to reference the field in the Source instance.
Trending object on layout	Trending object on layout	Create New Only	Do Not Override Layout	Referenced field does not exist in the Target instance. The field from the Source instance is created in the Target instance, and then referenced by the trending object in the Target instance.
Trending object on layout	Trending object on layout	Create New and Update	Do Not Override Layout	Target instance is updated with any trending chart properties that exist in the Source instance. The application layout is not changed.
Trending object on layout	Trending object on layout	Create New and Update	Override Layout	Target instance is updated with any trending chart properties that exist in the Source instance. The position of the trending object on the application layout and the span properties are updated to match the Source instance.
Trending object on layout	Trending object on layout	Create New Only	Override Layout	Position of the trending object on the application layout is updated. The field and trending object properties are not updated.
Trending object on layout	Placeholder on layout	Create New Only	Override Layout	The following message is displayed: Package Install Successful. The trending chart cannot be created in the Target instance for the following reasons: Referenced field is not trended. Packaging operation does not enable trending in the Target instance when Create New Only is selected.
Trending object on layout	Placeholder on layout	Create New and Update	Override Layout	Trending object and referenced field are created in the Target instance. Application layout matches the Source instance. Field in the Target instance is trending-enabled, and the associated trending chart is created in the Target instance.
Trending object on layout	Placeholder on layout	Create New Only	Do Not Override Layout	Trending object and referenced field are created in the Target instance. Application layout is not overridden.
Trending object on layout	Placeholder on layout	Create New and Update	Do Not Override Layout	Trending object and referenced field are created in the target. Application layout is not overridden.

Users and groups

Packaging rules related to users and groups include:

• The package installation process attempts to match all users in the package by user name and domain. The process ignores any users that do not match.

• The package installation process attempts to match all groups in the package by system ID. If no matches are found, the process then attempts to match groups by group name and domain. The process ignores any groups that do not match.

Values lists

Packaging rules related to values lists, which may include global values lists, questionnaire values lists, or custom values lists, include:

• If a global values list in the package file matches a custom values list in the target instance, the custom values list is promoted to a global values list during installation. However, the opposite is not true. A global values list in the target instance is not demoted to a custom values list during installation.

• The following values list values attributes are not updated if settings already exist in the target instance:

  • Height

  • Default text

• In custom ordered values lists, the source package determines the sort order of the values. All non-matching target items appear below the source values but in the same relative order.

Workflow

Packaging rules related to workflow include:

• If a package includes workflow settings, all workflow settings from the package are installed on the target instance and the prior workflow settings are overwritten. However, if you select the Create New Only option when installing a package and at least 1 stage already exists in the target instance, the package installation does not make any changes to the existing workflow settings. If no workflow stages have been defined in the target instance, and you select the Create New Only option, the package installation updates all workflow settings as specified in the package.

• If the package does not include any workflow settings, the package installation does not delete or modify any existing workflow settings in the target instance.

• Any records in a workflow stage that is deleted by the package installation are routed to the start point of the workflow process.

Workspaces and dashboards

Packaging rules related to workspaces and dashboards include:

If the package creates a new workspace or dashboard and there are not enough licenses, the new workspace or dashboard is set to the Development status and a warning is logged.