Package installation is very complicated under the hood. Proper attention while preparing the package for installation will set you up for success. This lesson includes topics like mapping assets, changing the actions you want to take for different assets, preparing and validating assets, handling conflicts and invalid assets, and editing assets before they are even installed.
This lesson assumes that you have started one or more package installations and are currently looking at the package installation dialog.
The package installation dialog displays all of the files assets that the package may modify on your site, including assets that you need to map or take some other action on in order for the package to be installed correctly.
All changes are saved immediately in the installation so if you leave the installation and return later you will not need to repeat any customization you have already completed.
If you would like to quit installing this package and remove any saved progress then select "Abandon". If you make too many unwanted changes during package installation this is also an easy way to reset to the original package installation settings.
When you are ready click “Install” and the package resources will be installed to your site. You can publish all the files at this point if you want them to be public. You may need to perform additional steps to set up the specific package. Each package is different and you should consult the package instructions for details.
The package installation dialog contains a built-in wizard which can walk you through your package installation. The wizard will prompt you to take action when necessary, such as mapping your assets or resolving conflicts. It is generally sufficient to simply follow the wizard when installing packages, but sometimes you may want to make additional customizations or understand more about how things work.
Each asset has an action associated with it, which you can change by clicking on the dropdown list and selecting from these options:
None - This asset will be skipped. If other assets reference this item then it may cause errors and you should map it.
Create/Update - The asset will be created or updated on your site
Map - If any assets to be created or udpated reference this asset, replace references to this asset with the object on your site that you select instead.
Trash - If the asset was created by a previous version of the package and later deleted from the package, the action may be set to trash the object on your site.
As mentioned above, mapping an asset means that any references to the asset in the package will instead be updated to reference the object that you select.
When the installation is started, Marketpath CMS sometimes automatically maps assets for you when it is able to determine what appears to be a good fit - either based on previous package installations, asset names, or other reasonable deductions.
You may also manually select what assets should be mapped to, including updating existing mappings or even selecting nothing at all (for optional assets). However, keep in mind that you may need to prepare your installation if you change any asset mappings - more on that later.
If you choose not to map any optional assets, references to those objects will simply be removed. In some cases that may cause other assets in your installation to become errored - in which case you will either need to select something to map the asset to or directly edit the errored assets in your installation before it may be completed.
After all of your assets have been mapped, your installation will need to be "prepared" - which is the process by which all references to assets in the package are replaced by references either to assets in the package or objects on your site.
There are sometimes conflicts created between old and new versions of a package. This happens when you install a package on your site, modify one or more of the objects from the package on your site, and then attempt to update to a newer version of the package. When this happens, you will have to decide whether to take the asset as it is defined in the package, to keep the object as it is on your site, or to edit the asset directly in the installation and take that version. Bear in mind that if you modify the asset in the installation, you may be prompted to take the same action the next time that the package is updated.
There are likely to be differences between your site and the site that a package was initially created on. Due to these differences, as well as differences that can be introduced during asset mapping, package installation may sometimes be halted in order to correct validation errors before creating or udpating objects on your site. There are several ways to address validation errors:
You can edit assets directly in the package installation before they are even installed.
When you initially open an asset for editing in an installation, it will take all of its original values directly from the package - which may be important to remember if you have a conflict between the package and your site.
When you save an assets in an installation, some validation is performed immediately (such as required fields and URL formats) and some validation is postponed until later (such as unique URLs). If the asset is "valid", it will be saved in the installation but the changes will not take effect on your site until you complete the installation.
Please fill out the form below with your feedback or any questions you may have after working through the "Preparing your package installations" lesson.