Using the Promotion Tools

Overview of Promotion Tools

Promotion is the process of copying selected metadata and associated content within or between planned deployments of SAS software. This process is repeatable for a particular deployment.

The SAS Intelligence Platform provides tools that enable you to promote individual metadata objects or groups of objects from one metadata server to another, or from one location to another on the same metadata server. You can also promote the physical files that are associated with the metadata.

The promotion tools include the following:

the Export SAS Package and Import SAS Package wizards, which are available in the Folders tab of SAS Management Console. The same wizards are also available in SAS Data Integration Studio and SAS OLAP Cube Studio.
the batch import tool and the batch export tool, which enable you to perform promotions on a scheduled or repeatable basis. These tools provide most of the same capabilities as the Export SAS Package and Import SAS Package wizards.

The promotion tools support the following types of scenarios:

promotion of objects from one location in the SAS Folders tree to another location in the same tree. For example, you might want to promote newly developed (or newly modified) objects from a user's home folder to a location under the Shared Data folder.
promotion of objects from a test environment to a production environment. For example, you might want to promote newly developed (or newly modified) objects from a metadata server that is installed on a test machine to a metadata server that is installed on a production machine.
importing objects that were exported from a SAS 9.1.3 environment. This feature is sometimes used to support migration from SAS 9.1.3 to SAS 9.2. It is also useful for sites that are running two SAS releases in parallel. Before exporting objects from the SAS 9.1.3 environment, make that sure you have the correct software version (see Special Considerations for Promoting Metadata From SAS 9.1.3 to SAS 9.2).

Note: Migration is the process of moving data to a different server or storage device, converting the data for use in a different operating environment, or both. Migration can include installing newer software and converting applications for use with that software.
creating a backup of specific folders and objects. In this case, you would use the Export SAS Package wizard or the batch export tool to create a package file. If you later need to restore the folders or objects, you would use the Import SAS Package wizard or the batch import tool to restore the contents of the package file to the metadata server.

The following table shows the types of objects that you can promote:

Note:

You might be able to export additional object types, depending on which applications you have installed.
In SAS Data Integration Studio and SAS OLAP Cube Studio, you can import and export only the objects that pertain to the application.
To promote portal pages, page templates, portlet instances, and the portal's application and user permissions trees, see Promoting Portal Content in the SAS Intelligence Platform: Web Application Administration Guide.

Types of Objects That Can Be Promoted
Actions Applications Burst definitions Channels Conditions Condition action sets Content subscribers Content subscriber groups Cubes Dashboard objects^* Data explorations Deployed flows Deployed jobs	Documents Event subscribers Event subscriber groups External files Folders Generated transformations Information maps Jobs Libraries Message queues Mining results Notes OLAP schemas	Prompts Prompt groups Queue managers Reports Report components Report images SAS Add-In for Microsoft Office documents SAS Enterprise Guide projects Stored processes Tables Web services
* Dashboard objects (including dashboards, indicators, indicator data, ranges, indicator configurations, and dashboard components) can be promoted effective with the November 2010 release. However, these objects cannot be promoted within the same metadata server. For additional special considerations, see "Promoting SAS BI Dashboard 4.3 Content" in the SAS Intelligence Platform: Web Application Administration Guide.

Overview of the Promotion Process

Promotion is a three-step process:

First, you must prepare the source and target environments. The preparation steps include ensuring that the required servers are configured and running. If you are promoting metadata from one metadata server to another, you must prepare the target environment by creating folders for the metadata, creating directories for the physical files, and setting up security. For details, see Preparing to Use the Promotion Tools.
Second, you use the Export SAS Package wizard (or the batch export tool) to export the selected objects or folders from the source metadata server. The wizard or the batch tool places the exported objects in a SAS package (SPK) file. If you want the SPK file to be available remotely, then you can direct the package to a shared location within your file system. You can also e-mail the package after it has been created.
Third, you use the Import SAS Package wizard (or the batch import tool) to import the package file. You can import the package to another metadata server, which can be located either on the same host machine or a different host machine; or you can import it to a different location in the SAS Folders tree on the source metadata server.

Three-step Promotion Process

[Diagram of three-step promotion process]

The package format is the same regardless of whether the package is created in SAS Management Console, in SAS Data Integration Studio, in SAS OLAP Cube Studio, or by the batch export tool. In addition, the package format is the same regardless of the host machine's operating system. Therefore, packages can be interchanged as follows:

A package that is exported by using SAS Management Console can be imported by using SAS Data Integration Studio or SAS OLAP Cube Studio, and vice versa. However, SAS Data Integration Studio and SAS OLAP Cube Studio can import and export only the objects that pertain to the application, whereas SAS Management Console can import and export all object types that are listed in Types of Objects That Can Be Promoted.
A package that is exported by using the Export SAS Package wizard can be imported by using the batch import tool.
A package that is exported by using the batch export tool can be imported by using the Import SAS Package wizard.
You can export a package from a Windows system and import it to a UNIX system, and vice versa.

Selective Promotion

The Export SAS Package and the Import SAS Package wizards (and the batch export and import tools) provide the following options for specifying which objects are to be exported and imported:

You can select multiple nested folders.
You can include all of the objects that are contained in a folder or just selected objects, as shown in the following example:
You can include or exclude dependent objects.

In the Export SAS Package wizard, as shown in the preceding example, you can highlight one or more objects and view their dependencies. You can then select which dependent objects you want to include in the export.

In the batch export tool, you can specify that all dependent objects are to be identified recursively and included in the export.
You can use the Filter feature, as shown here, to select objects based on the object name, the object type, or the time period during which the object was created or last modified. In addition, you can select Include empty folders if you want to export folders that do not contain any subfolders or objects. (If you do not select this option, then empty folders are not exported.)
When importing a package, you can import all objects in the package or just new objects (that is, objects that do not already exist in the target folder location).

Promotion of Content Along With Metadata

For most object types, the Export SAS Package and Import SAS Package wizards (and the batch export and import tools) promote both the content and the metadata. When you use the batch tools, the promotion automatically includes all associated content except tables and external files. When you use the wizards, you can choose whether to include or exclude some of the content types.

The following table lists the types of content that are exported and imported with metadata objects.

Promotion of Content with Metadata Objects
Object	Associated Content	Promotion Details
Channel	Packages published to the channel's archive or WebDAV location	Associated content is always promoted with batch tools and is optionally promoted with wizards.
Cube	Cube header files, MOLAP aggregation tables, drill-through tables, and ROLAP aggregation tables	Associated content is not promoted. For details about moving these files, see the SAS OLAP Server: User's Guide.
External file	Physical file	Associated content is not promoted with batch tools and is optionally promoted with wizards.
External file	External format file (EFF)	Associated content is not promoted with batch tools and is optionally promoted with wizards.
Job	Custom code, preprocesses, and postprocesses.	Associated content is always promoted.
Library	XML files and XML maps that are contained in the library	Associated content is always promoted with batch tools and is optionally promoted with wizards.
Prompt	Physical files that are associated with File or directory prompts	Associated content is not promoted. For details, see Create Directories and Move Physical Files for Prompts.
Report	XML (.srx) file that defines the report	Associated content is always promoted. The target is the path on the SAS Content Server or file system that is mapped to the target metadata folder via content mapping.
Stored process	Source code (.sas) file	Associated content is optionally promoted with the wizards and is always promoted with the batch tools. The target is the source code repository that you designate in the wizard dialog box. If the repository definition does not exist on the target system, the Import SAS Package wizard allows you to add it. When you use the batch import tool, you can use the substitution file to designate the source code repository and to specify that the repository definition is to be created if it does not exist.
Table	Physical table	Associated content is not promoted with the batch tools and is optionally promoted with the wizards. Use this option with small data sets only. Since data sets are packaged in the .spk file, large data sets could require lengthy processing times.

If the promotion of an object's associated content is optional, information about the associated content is displayed in the wizard's Options tab. In the following example, a stored process object is highlighted, and the Options tab displays a check box for including the source code with the stored process. The check box is selected by default.

[Export Wizard screen with Options tab displayed]

When you export or import a table or an external file, the option to include the content is not selected by default.

Restoration of Metadata Associations

Depending on the types of objects that you are importing, you might need to establish associations with the following objects and entities on the target system:

a SAS Application Server
a SAS Content Server
base path on a SAS Content Server
libraries
tables
external files
physical locations for external files or for libraries
physical locations for custom code that is associated with jobs, if the code is stored outside of the metadata
OLAP schemas
mining results
a source code repository (for stored processes)

You can choose to restore the same metadata associations that were established in the source environment, or you can establish different associations.

The Import SAS Package wizard displays prompts that assist you in associating imported objects with the appropriate objects and entities in the target environment. If you are using the batch tools, then you can specify the associations in the substitution properties file (see Using the Substitution Properties File).

Optional Promotion of Access Controls

You can include direct assignments of access control entries (ACEs) and access control templates (ACTs) in the promotion process. The following limitations apply to the promotion of access controls using the Export SAS Package and Import SAS Package wizards and the batch export and import tools:

The promotion tools cannot promote ACTs, but they can promote direct associations between ACTs and objects. In order for an object's ACT association to be promoted, an ACT of the same name must exist in the target metadata server.
Access control entries and ACT associations that are inherited from a folder are not promoted. For inheritance to take effect in the target metadata server, you must also promote the folder that contains the direct access control entries or ACT association.
Access control entries are not promoted if they refer to users or groups that do not exist in the target metadata server.

If you do not specify that you want to include access controls in the promotion process, then access controls are applied as follows:

If you import an object that already exists in the target metadata server, then the permissions that have been applied to the existing object are preserved when you overwrite the object.
If you import an object for the first time, then the object inherits permissions from the folder into which the object is imported.

Top of Page