Promotion Details for Specific Object Types

Promoting Access Controls
About Promoting Access Controls
Using the Include Access Controls Option
Applying Access Controls Directly in the Target Environment
Promoting Dashboard Objects
Promoting Libraries and Tables
Promoting OLAP Content
Promoting Portal Content
Promoting Prompts
Promoting Queue Managers
Promoting SAS Enterprise Guide Projects and SAS Add-In for Microsoft Office Documents
Promoting Secured Data Folders, Secured Library Objects, and Secured Table Objects
Promoting Security Objects and Server Objects
About Promoting Security Objects and Server Objects
Promoting Security Objects (Users, User Groups, Roles, and Access Control Templates)
Promoting Server Objects
Promoting SAS Application Servers and Associated Spawners

Promoting Access Controls

About Promoting Access Controls

When you promote objects, you can choose to also promote the objects’ access controls, subject to the following limitations:
  • In order for an object’s ACT association to be promoted, an ACT of the same name must exist in the target metadata server. For best results, you should always promote security objects (including users, user groups, roles, and ACTs) first, in a separate package, before you promote the objects with which they are associated.
  • An object’s access control entries are not promoted if they refer to users or groups that do not 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.

Using the Include Access Controls Option

If you want to include direct assignments of access control entries (ACEs) and access control templates (ACTs) in the promotion process, the following steps are recommended:
  • Ensure that you have done the following in the source environment:
    • Set up user groups that mirror the groups that will exist in the target environment, and define a small number of users in each group for testing purposes.
    • Create ACTs that define the permission levels for each user group, apply the ACTs to objects and folders, and test the ACTs to ensure that the appropriate level of security is applied.
    • Instead of (or in addition to) ACTs, apply ACEs to folders and objects to define the permission levels for each user group. Test the ACEs to ensure that the appropriate level of security is applied.
  • Promote the ACTs and user groups to the target environment (or create them in the target environment) before you import the affected objects. Make sure that the ACTs and groups have the same names in both environments.
  • When you import the affected objects to the target system, select the Include access controls option in the import wizard (or specify -includeACL in the batch import command). Each object’s access control template (ACT) associations and access control entries (ACEs) will then be promoted and will be re-established in the target environment.
    Note:
    • In order for the ACT associations and the ACEs to be promoted, you must promote the objects or folders to which the ACTs were directly applied. Inherited ACT associations and ACEs are not promoted.
    • If the imported objects already exist on the target metadata server, then any existing access controls for these objects (including access controls that are inherited) will be overwritten by the imported ACTs and ACEs.
    • Access controls for folders are promoted only if the imported folders do not already exist on the target metadata server. If a folder already exists, its access controls are not overwritten by the imported ACTs and ACEs.

Applying Access Controls Directly in the Target Environment

Instead of promoting access controls, you can choose to apply ACTs or ACEs to folders and objects directly in the target environment. For this option, you need to define user groups, ACTs, and ACEs only in the target environment instead of in both environments. This option involves fewer steps, but it does not provide the opportunity to test your security settings before promotion.
For this option, do not select the Include access controls option in the import wizard. If you are using the batch import command, then omit the -includeACL option. Access controls for the imported objects will be 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.

Promoting Dashboard Objects

Dashboard objects (including dashboards, indicators, indicator data, ranges, indicator configurations, and dashboard components) can be promoted only within the same release. For example, you can promote dashboard objects from one SAS 9.3 deployment to another, but you cannot promote them from a SAS 9.2 deployment to a SAS 9.3 deployment.
For additional details about promoting dashboards, see Promoting SAS BI Dashboard Content in SAS Intelligence Platform: Web Application Administration Guide.

Promoting Libraries and Tables

The following special considerations apply to promoting libraries and tables:
  • Library names must be unique within a SAS Application Server. When you import a library, the promotion tools check to determine whether the target environment contains a library that has the same name and is located on the same application server. If such a library exists, then the promotion tool renames the imported library to Copy of library-name.
  • Table names must be unique within a library. When you import a table, the promotion tools check to determine whether the target environment contains a table that has the same name and is part of the same library. If such a table exists, then the promotion tool renames the imported table to Copy of table-name.
  • The promotion tools do not create the physical directory paths that are needed for libraries. Instead, the import tools check to determine whether the directory that is defined in metadata exists in the target environment.
  • If you choose to export physical tables along with metadata, you should be aware that large data sets could require lengthy processing times (since data sets are packaged in the SPK file along with the metadata).
    Note: When you use export table objects with the batch export tool, the physical tables cannot be exported.
  • If you import metadata for a table or an external file that is already registered in the target environment, then any matching column metadata is overwritten by default. Any non-matching metadata in the target table or file is preserved. The matching of column names is case-insensitive. For example, metadata for a column called SALES will overwrite metadata for a column called Sales.
    To override the default behavior for resolving column differences, you can use the Change Analysis feature of the import wizard or set global optionsfor the batch import tool.

See Also

Promoting Tables and Libraries from SAS 9.1.3 to SAS 9.3

Promoting OLAP Content

An environment can contain only one OLAP schema for each SAS Application Server. If an application server has an OLAP schema and you try to import another one for the same server, the import wizard prompts you to either deselect the schema or select a different application server.
The following special considerations apply to promoting OLAP cubes:
  • Before you promote cubes, you must create directories on the target system for the associated physical files (including cube header files, MOLAP aggregation tables, drill-through tables, and ROLAP aggregation tables).
  • OLAP cubes must be promoted along with their associated jobs. The export wizard will not allow you to continue if you do not select both objects. You can use the Dependencies tab to identify the jobs.
  • After you promote the metadata and jobs for an OLAP cube, you must rebuild the cube.
For important details about these and other tasks that are associated with promoting cubes, see the SAS OLAP Server: User's Guide.

See Also

Promoting OLAP Cubes from SAS 9.1.3 to SAS 9.3

Promoting Portal Content

The wizards and batch tools cannot promote portal pages, page templates, portlet instances, or the portal's application and user permissions trees. To promote these items, you can use the content promotion tool for the SAS Information Delivery Portal 4.3. See About the Portal Promotion Tools in SAS Intelligence Platform: Web Application Administration Guide.

Promoting Prompts

If you promote an object (for example, a stored process or a shared prompt) that includes a File or directory prompt, then you must do the following:
  • After the promotion is complete, you must edit the prompt to ensure that a valid workspace server is specified.
  • If the File or directory prompt has a default file or directory value specified, then you must move the associated physical file or directory to the target environment, if it is not already present. After the promotion, you must edit the prompt to associate it with the correct file or directory.

See Also

Promoting Prompts from SAS 9.1.3 to SAS 9.3

Promoting Queue Managers

If you export a queue manager for WebSphere object or a queue manager for MSMQ object, then all of the message queues that are defined for that object are also exported, regardless of whether they were selected. When you import the package, the message queues might be added to your metadata. If you do not want to use the message queues, you should delete them when the import is complete.

Promoting SAS Enterprise Guide Projects and SAS Add-In for Microsoft Office Documents

After you promote a SAS Enterprise Guide project or a SAS Add-In for Microsoft Office document, you might need to update the application server names for tables that are associated with the project or document. This step is necessary if the target environment uses different application server names than the source environment. After you perform the promotion, use one of the following methods in the target environment to adjust the metadata:
  • Run the migration wizard that is provided with SAS Enterprise Guide and SAS Add-In for Microsoft Office. For details, see “Using the Migration Wizard” in Administering SAS Enterprise Guide; or see “Migrating SAS Content” in the SAS Add-In for Microsoft Office Help.
  • For SAS Enterprise Guide projects, use the Project Maintenance dialog box to edit the table metadata. For details, see the SAS Enterprise Guide Help.

Promoting Secured Data Folders, Secured Library Objects, and Secured Table Objects

The following special considerations apply to promoting secured data folders, secured library objects, and secured table objects that have been created to support metadata-bound libraries:
  • The target metadata folder path and folder name must be the same as the source metadata folder path and folder name. Import and export of secured data folders, secured library objects, and secured table objects is primarily for transfer of these metadata objects from one metadata server to another. For example, you might promote these objects from a development server to a test server and then to a production server.
    Note: It is also possible to import these objects into the same metadata server, folder path, and folder from which you exported them. You might use this method to back up and restore these objects.
  • You cannot explicitly choose which secured table objects to import or export. All secured table objects within each secured library object are ported with that secured library object.
  • After the initial import of a secured library object into a new target metadata server, you must use SAS code to apply passwords to the new target library. (For security reasons, passwords are not ported.) See documentation for the MODIFY statement in the SAS Guide to Metadata-Bound Libraries.
    Tip
    When you submit the code to add password information to the secured library object in the new target server, remember to specify options (or adjust configuration) in your SAS session so that it connects to the new target metadata server (where the passwords do not yet exist), instead of the source metadata server (where the passwords already exist).
    This requirement applies to only the first import of each secured library object into a new server (and to the first such import after the passwords for the source library object are changed). Other imports of the same secured library object into the same target server include a step that retrieves the already-present passwords from the pre-import target objects and updates the post-import target objects with those passwords.
  • As a best practice, you should maintain a separate copy of your physical data for each environment (for example, development, test, and production). The alternative, pointing multiple metadata servers at the same physical data, is supported but introduces significantly more complexity.
Note: Like promotion of a regular folder, promotion of a secured data folder can include direct access controls (both explicit and ACT) only if the corresponding secured data folder does not already exist in the target server. If the corresponding secured data folder already exists in the target server, that folder’s direct access controls are not modified, updated, or overwritten by the import process.
For information about metadata-bound libraries, see the SAS Guide to Metadata-Bound Libraries.

Promoting Security Objects and Server Objects

About Promoting Security Objects and Server Objects

In SAS 9.3, the object types that you can promote include security objects (users, user groups, roles, and access control templates) and server objects (SAS Application Servers and their component servers, SAS object spawners, and SAS/CONNECT spawners). In the second maintenance release for SAS 9.3, promotion support was added for additional server types.
The promotion of security and server objects can be useful when you are creating or refreshing a SAS environment that mirrors an existing environment. For example, you can use this feature to help create a test environment that mirrors your production environment and to refresh the test environment as needed. Or you might choose to create server or security objects in a test environment and then promote the objects to your production environment after the objects have been tested.
To support the promotion of server and security objects, the SAS Folders tree in SAS Management Console contains virtual folders called Servers and Security. These folders are referred to as virtual folders because they do not actually store metadata objects. The virtual folders are represented by white folder icons (Virtual folder icon (white folder)) and are located in the path /System in the Foundation repository and in each custom repository. These folders appear only in SAS Management Console. Therefore, you can promote server and security objects only with SAS Management Console and the batch export and import tools. You cannot use SAS Data Integration Studio or SAS OLAP Cube Studio to promote these objects.
Note: Server and security objects can reside only in the appropriate virtual folders. They cannot be moved or promoted to other folders. In addition, the Server and Security virtual folders can be used only for server and security objects. You cannot move or promote other types of objects into these folders.
Follow these guidelines when importing security and server objects:
  • If a package includes security objects and server objects, then you must import the package to SASFolders/System or higher. Be sure to select the option Preserve source path information for objects in the package so that the wizard will place each object in the appropriate virtual folder.
  • If the package contains additional objects that are not security or server objects (for example, if the package contains stored processes), then you must import the package at the SASFolders level. Be sure to select the option Preserve source path information for objects in the package so that the wizard will place each security and server object in the appropriate virtual folder.
CAUTION:
For best results, you should always promote security or server objects first, in a separate package, before you promote the objects with which they are associated.

Promoting Security Objects (Users, User Groups, Roles, and Access Control Templates)

You can promote security objects from the Security virtual folder, which is located in the path /System. The folder has subfolders for access control templates, authentication domains, roles, user groups, and users, as shown here:
Security virtual folder and its subfolders
Note:
  • Authentication domains cannot be promoted. If an imported user or server depends on an authentication domain that does not exist in the target environment, the domain is automatically created during the import process.
  • The Authentication Domains and Users subfolders are present only in the Foundation repository.
The following special considerations apply to the promotion of security objects:
  • Associations among objects are retained as follows:
    • When you import objects (for example, information maps) whose security is being controlled, their associations with security objects (users, user groups, and ACTs) are retained if the security objects already exist on the target system or are promoted in the same package. As a best practice, you should import security objects first in a separate package.
    • When users are imported, their associations with ACTs, user groups, and roles are retained if these objects either exist in the target system or are promoted in the same package as the users.
    • When user groups are imported, their associations with ACTs, users, and roles are retained if these objects exist in the target system or are promoted in the same package as the groups.
    • When roles are imported, their associations with users and user groups are retained if the users and user groups exist on the target system or are promoted in the same package as the roles.
    • When ACTs are imported, their associations with users and user groups are retained if the users and user groups exist on the target system or are promoted in the same package as the ACTs.
    If the associated objects do not exist in the target system (or are not included in the package) as described in the preceding list, the associations are removed.
    On the Select Objects to Export page, you can use the Dependencies and Used by tabs as needed to identify and select the groups that a user belongs to, the users that make up a group, and the users and groups that an ACT depends on. (Dependency and “used by” information is not available for roles.)
  • If a package includes multiple types of security objects, then you must import the package to SASFolders/System/Security or higher. Be sure to select the option Preserve source path information for objects in the package.
  • When users are imported, the following special considerations apply to the promotion of user login (account) information:
    • If a user already exists on the target system, the import operation does not overwrite the user’s existing logins. However, if an imported user object contains a login for an authentication domain for which the user has no existing logins, the login is added.
      For example, suppose the target system contains one login for a user named Joel, and that the login specifies the DefaultAuth domain. If the imported package contains a login for Joel that specifies the DefaultAuth authentication domain, then that login is not imported. If the imported package contains a login for Joel that specifies a different domain (for example, Auth2), then that login is imported.
    • Passwords that are included in the logins of external accounts are not included in the import. These passwords must be added to logins manually after the import is complete.
      Note: Passwords for internal accounts are included in the import.
    • Machine names in stored user IDs are not updated during the import process. You must update them manually after the import is complete.
  • Users cannot be promoted to a custom repository.
  • When a user is promoted, application preferences that are associated with the user are not included in the promotion. (However, preference information is included in migrations that are performed using the SAS Migration Utility. See the SAS Intelligence Platform: Migration Guide.)
  • When a user object is overwritten by an imported user object, any application preferences that are associated with the user on the target system are erased.

Promoting Server Objects

You can promote server objects from the Server virtual folder, which is located in the path /System. The initial release of SAS 9.3 supports the promotion of SAS Application Servers and their component servers, SAS object spawners, and SAS/CONNECT spawners.
The second maintenance release for SAS 9.3 supports the promotion of additional server types including the following: content servers, database servers, DataFlux Federation Servers, enterprise application servers, generic batch servers, grid monitoring servers, Hadoop servers, message queue polling servers, SAS/SHARE servers, SAS Scalable Performance Data (SPD) servers, and all types of scheduling servers. If you need to promote one of these servers, but the server does not appear in the System/Servers folder in SAS Management Console, then follow these steps to adjust the server metadata:
  1. Make sure your software, including SAS Management Console, is current as of the second maintenance release for SAS 9.3.
  2. Back up your metadata server. See Backing Up and Recovering the SAS Metadata Server.
  3. Run the Upgrade Metadata utility. To do so, go to the Plug-ins tab of SAS Management Console and select Environment Managementthen selectMetadata Managerthen selectActive Server. Then right-click the Active Server node, and select Upgrade Metadata.
    After the utility executes, the servers should appear in the System/Servers folder.
The following special considerations apply to the promotion of servers:
  • Server names must be unique within a metadata server. If the target metadata server already has a server with the same name as an imported object, then the promotion tool renames the imported object to Copy of object-name.
  • The import wizard displays prompts that enable you to provide new values for host machine names, server ports, and paths and script names for server start-up commands. For each of these attributes, provide values that are valid for the target environment. The Summary page that appears at the end of the wizard process displays the old and new values for each attribute. Before completing the import operation, review this page to ensure that your entries are correct.
    If you are using the batch import tool, then use the substitution properties file to specify these values.
    Note: When you promote a SAS/SHARE server, the servers’s port number cannot be updated.
    Note: When you promote an HTTP server, the base path cannot be updated. However, you can edit the path in the server properties after the promotion is completed.
  • The promotion tools do not copy the physical files that are associated with servers, such as start-up scripts and server configuration files. These files must be copied to the target environment manually.
  • SAS Framework Data Servers cannot be promoted.
If you need to promote a SAS Application Server and its components, see the additional considerations in Promoting SAS Application Servers and Associated Spawners.

Promoting SAS Application Servers and Associated Spawners

Generally, when you promote objects that depend on SAS Application Servers, it is not necessary to promote the application server objects. Instead, you can use the import wizard (or the substitution properties file) to associate imported objects with servers that already exist on the target system.
For situations in which you do need to promote metadata for application server objects, the Servers virtual folder contains a node for each SAS Application Server and each application server component that is configured on your system, as shown here:
The System node of the SAS Folders tree with the Servers virtual folder expanded
The spawners that are associated with the servers are displayed in the right panel when the Servers folder is selected. The spawners do not appear on the Folders tab.
The following special considerations apply to the promotion of SAS Application Servers:
  • When you promote an application server, all of its components are included in the promotion. You cannot select individual server components (for example, specific workspace servers) to export or import.
  • On the Select Objects to Export page, you can use the Dependencies tab as needed to identify and select the spawners that are associated with each application server.
Copyright © SAS Institute Inc. All rights reserved.