Adobe Campaign allows you to export or import the platform configuration and data through a package system. Packages can contain different kinds of configurations, elements, filtered or not.
Data packages let entities of the Adobe Campaign database be displayed via files in XML format. Each entity contained in a package is represented with all of its data.
The principle of data packages is to export a data configuration and integrate it into another Adobe Campaign system. Learn how to maintain a consistent set of data packages in this section.
There are three types of exportable packages: user packages, platform packages and admin packages.
User package: it enables you to select the list of entities to be exported. This type of package manages dependencies and verifies errors.
Admin package: it includes all added templates and business objects (non standard): templates, libraries, etc.
The platform and admin types contain a predefined list of entities to be exported. Each entity is linked to filtering conditions that enable you to remove the out-of-the-box resources of the created package.
The description of a data package is a structured XML document that complies with the grammar of the xrk:navtree data schema.
Data package example:
<package> <entities schema="nms:recipient"> <recipient email="email@example.com" lastName="Smith" firstName="John"> <folder _operation="none" name="nmsRootFolder"/> <company _operation="none" name="Adobe"/> </recipient> </entities> <entities schema="sfa:company"> <company name="Adobe"> location city="London" zipCode="W11 2BQ"/> </company> </entities> </package>
The XML document must begin and end with the
<package> element. Any
<entities> elements that follow distribute the data by document type.
<entities> element contains the data of the package in the format of the data schema entered in the schema attribute.
The data in a package must not contain internal keys that are not compatible between bases, such as auto-generated keys (autopk option).
In our example, the joins on the “folder” and “company” links have been replaced by so-called “high level” keys on the destination tables:
<recipient> <folder _operation="none" name="nmsRootFolder"/> <company _operation="none" name="Adobe"/> </recipient>
operation attribute with the value “none” defines a reconciliation link.
A data package can be constructed manually from any text editor. Simply ensure that the structure of the XML document complies with the “xtk:navtree” data schema. The Adobe Campaign console has a data package export and import module.
Packages can be exported in three different ways:
Once a package exported, you will be able to import it and all the added entities into another Campaign instance.
The package export wizard is accessible via the Tools > Advanced > Export package… menu of the Adobe Campaign client console.
For the three types of packages, the wizard offers the following steps:
List the entities to be exported by document type:
If you export an Offer category, Offer environment, Program or Plan type folder, don’t ever select the xtk:folder as you may lose some data. Select the entity that corresponds with the folder: nms:offerCategory for offer categories, nms:offerEnv for offer environments, nms:program for programs, and nms:plan for plans.
List management lets you add or delete entities for export from the configuration. Click Add to select a new entity.
The Detail button edits the selected configuration.
The dependency mechanism controls the entity export sequence. For more on this, refer to Managing dependencies.
The entity configuration screen defines the filter query on the type of document to be extracted.
You must configure the filtering clause for data extraction.
The query editor is presented in this section.
Click Next and select the sorting columns to order the data during extraction:
Preview the data to extract before running the export.
The last page of the package export wizard lets you start the export. The data will be stored in the file indicated in the File field.
The export mechanism enables Adobe Campaign to track the links between the various exported elements.
This mechanism is defined by two rules:
Integrity types linked to schema elements are defined in this section.
Here is an example on how to export a campaign. The marketing campaign to be exported contains a task (label: “MyTask”) and a workflow (label: “CampaignWorkflow”) in a “MyWorkflow” folder (node: Administration / Production / Technical workflows / Campaign processes / MyWorkflow).
The task and the workflow are exported in the same package as the campaign since the matching schemas are connected by links with an “own” type integrity.
<?xml version='1.0'?> <package author="Administrator (admin)" buildNumber="7974" buildVersion="7.1" img="" label="" name="" namespace="" vendor=""> <desc></desc> <version buildDate="2013-01-09 10:30:18.954Z"/> <entities schema="nms:operation"> <operation duration="432000" end="2013-01-14" internalName="OP1" label="MyCampaign" modelName="opEmpty" start="2013-01-09"> <controlGroup> <where filteringSchema=""/> </controlGroup> <seedList> <where filteringSchema="nms:seedMember"></where> <seedMember internalName="SDM1"></seedMember> </seedList> <parameter useAsset="1" useBudget="1" useControlGroup="1" useDeliveryOutline="1" useDocument="1" useFCPValidation="0" useSeedMember="1" useTask="1" useValidation="1" useWorkflow="1"></parameter> <fcpSeed> <where filteringSchema="nms:seedMember"></where> </fcpSeed> <owner _operation="none" name="admin" type="0"/> <program _operation="none" name="nmsOperations"/> <task end="2013-01-17 10:07:51.000Z" label="MyTask" name="TSK2" start="2013-01-16 10:07:51.000Z" status="1"> <owner _operation="none" name="admin" type="0"/> <operation _operation="none" internalName="OP1"/> <folder _operation="none" name="nmsTask"/> </task> <workflow internalName="WKF12" label="CampaignWorkflow" modelName="newOpEmpty" order="8982" scenario-cs="Notification of the workflow supervisor (notifySupervisor)" schema="nms:recipient"> <scenario internalName="notifySupervisor"/> <desc></desc> <folder _operation="none" name="Folder4"/> <operation _operation="none" internalName="OP1"/> </workflow> </operation> </entities> </package>
Affiliation to a type of package is defined in a schema with the @pkgAdmin and @pkgPlatform attribute. Both these attributes receive an XTK expression that defines the conditions of affiliation to the package.
<element name="offerEnv" img="nms:offerEnv.png" template="xtk:folder" pkgAdmin="@id != 0">
Finally, the @pkgStatus attribute enables you to define the export rules for these elements or attributes. Depending on the value of the attribute, the element or attribute will be found in the exported package. The three possible values for this attribute are:
The preCreate value is only admitted for link type events. It authorizes you to create or point towards an entity not yet loaded in the exported package.
Package definitions let you create a package structure in which you add entities that will be exported later on in a single package. You will then be able to import this package and all the added entities into another Campaign instance.
Package definitions can be accessed from the Administration > Configuration > Package management > Package definitions menu.
To create a package definition, click the New button, then fill in the package definition general information.
You can then add entities to the package definition, and export it to an XML file package.
In the Content tab, click the Add button to select the entities to export with the package. Best practices when selecting entities are presented in the this section section.
Entities can be added to a package definition directly from their location in the instance. To do this, follow the steps below:
Right-click the desired entity, then select Actions > Export in a package.
Select Add to a package definition, then select the package definition to which you want to add the entity.
The entity is added to the package definition, it will be exported with the package (see this section).
Package generation can be configured from the package definition Content tab. To do this, click the Generation parameters link.
Include the definition: includes the definition currently used in the package definition.
Include default values: adds to the package the values of all the entities’ attributes.
This option is not selected by default, in order to avoid lengthy exports. This means that entities’ attributes with default values (‘empty string’, ‘0’, and ‘false’ if not defined otherwise in the schema) will not be added to the package and will therefore not be exported.
Unselecting this option can result in a merge of local and imported versions.
If the instance where the package is imported contains entities that are identical to those of the package (for example with the same external ID), their attributes will not be updated. This can occur if the attributes from the former instance have default values, as they are not included in the package.
In that case, selecting the Include default values option would prevent versions merging, as all attributes from the former instance would be exported with the package.
To export a package from a package definition, follow the steps below:
Select the package definition to export, then click the Actions button and select Export the package.
An XML file corresponding to the exported package is selected by default. It is named according to the package definition namespace and name.
Once the package name and location defined, click the Start button to launch the export.
The package import wizard is accessible via the main menu Tools > Advanced > Import package of the Adobe Campaign client console.
You can import a package from an export performed earlier, e.g. from another Adobe Campaign instance, or a built-in package, depending on the terms of your license.
To import an existing data package, select the XML file and click Open.
The content of the package to be imported is then displayed in the middle section of the editor.
Click Next and Start to launch the import.
Standard packages are built-in packages, installed when the Adobe Campaign is configured. Depending on your permissions and your deployment model, you can import new standard packages if you acquire new options or add-ons, or if you upgrade to a new offer.
Refer to your license agreement to check which packages you can install.
For more information on built-in packages, refer to this page.
This section describes how to organize data packages in a consistent way across the life of the project.
Packages can contain different kinds of configurations and elements, filtered or not. If you miss some elements or do not import elements/packages in the correct order, the platform configuration can break.
Moreover, with several people working on the same platform with a lot of different features, the package specifications folder can quickly become complex.
Although it is not mandatory to do so, this section offers a solution to help organize and use packages in Adobe Campaign for large-scale projects.
The main constraints are as follows:
For more on setting up a workflow to automatically export packages, see this page.
Always import within the same version of the platform. You must check that you deploy your packages between two instances that have the same build. Never force the import and always update the platform first (if the build is different).
Importing between different versions is not supported by Adobe.
Pay attention to the schema and database structure. Importation of package with schema must be followed by schema generation.
Start by defining different types of packages. Only four types will be used:
If you need to deploy your configuration on a new instance, you can import all your entity packages.
This type of package:
This package is not mandatory. It is sometimes useful to create a specific type for all campaigns, even if a campaign can been seen as a feature.
Once configured, a feature can be exported into another environment. For example, the package can be exported from a dev environment to a test environment. In this test, a defect is revealed. First, it needs to be fixed on the dev environment. Then, the patch should be applied to the test platform.
The first solution would be to export the whole feature again. But, to avoid any risk (updating unwanted elements), it is safer to have a package containing only the correction.
That’s why we recommend creating an “update” package, containing only one entity type of the feature.
An update could not only be a fix, but also a new element of your entity/feature/campaign package. To avoid deploying the whole package, you can export an update package.
Now that types are defined, we should specify a naming convention. Adobe Campaign does not allow to create subfolders for package specifications, meaning that numbers is the best solution for staying organized. Numbers prefix package names. You can use the following convention:
It is better to set up rules for defining the correct number of packages.
To help the import, entity packages should by ordered as they will be imported. For example:
Forms should be imported only after schema updates.
Package number “200” should not be used for a specific campaign: this number will be used to update something that concerns all campaigns.
The last point concerns the update package numbering. It is your package number (entity, feature, or campaign) with a “5” as prefix. For example:
The update package should only contain one specific entity, in order to be easily reusable. To split them, add a new number (start from 1). There are no specific ordering rules for these packages. To better understand, imagine that we have a 101 feature, a social application:
When you update a package, you should always put a comment in the description field to detail any modifications and reasons (for example, “add a new schema” or “fix a defect”).
You should also date the comment. Always report your comment on an update package to the “parent” (package without the 5 prefix).
The description field can only contain up to 2.000 characters.