Work with data packages working-with-data-packages

About data packages about-data-packages

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.

Types of packages types-of-packages

There are three types of exportable packages: user packages, platform packages and admin packages.

Data structure data-structure

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="john.smith@adobe.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.

An <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>

The 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.

Export packages exporting-packages

About package export about-package-export

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.

Export a set of objects in a package exporting-a-set-of-objects-in-a-package

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:

Manage dependencies managing-dependencies

The export mechanism enables Adobe Campaign to track the links between the various exported elements.

This mechanism is defined by two rules:

Export a campaign exporting-a-campaign

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.

Package content:

<?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:

Manage package definitions managing-package-definitions

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.

Related topics:

Create a package definition creating-a-package-definition

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.

Related topics:

Add entities to a package definition adding-entities-to-a-package-definition

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:

Configure package definitions generation configuring-package-definitions-generation

Package generation can be configured from the package definition Content tab. To do this, click the Generation parameters link.

Export packages from a package definition exporting-packages-from-a-package-definition

To export a package from a package definition, follow the steps below:

Import packages importing-packages

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.

Install a package from a file installing-a-package-from-a-file

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.

Install a built-in package installing-a-standard-package

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.

Data package best practices data-package-best-practices

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:

Recommendations data-package-recommendations

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).

Pay attention to the schema and database structure. Importation of package with schema must be followed by schema generation.

Solution data-package-solution

Package types package-types

Start by defining different types of packages. Only four types will be used:

Entities

If you need to deploy your configuration on a new instance, you can import all your entity packages.

Features

This type of package:

Campaigns

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.

Updates

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.

Naming conventions data-package-naming

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:

Packages data-packages

Entity packages order entity-packages-order

To help the import, entity packages should by ordered as they will be imported. For example:

Package 200 package-200

Package number “200” should not be used for a specific campaign: this number will be used to update something that concerns all campaigns.

Update package update-package

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:

Package documentation package-documentation

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).