Scenario: Transfer Active Roles configuration
This scenario explains how to use the ARSconfig command-line tool to transfer a set of configuration objects from a test Active Roles instance to a production instance.
Suppose you need to transfer the following configuration objects from a test Active Roles instance to a production Active Roles instance:
- The Configuration/Access Templates/Common container, including all child objects stored in this container.
- The Configuration/Managed Units/Development container, excluding the child objects stored in this container.
- All child objects stored in the Script Modules/Corporate Policy/Priority Access container, but excluding the container itself.
Also, assume that the names of the domains managed by the test (source) Active Roles instance are test1.company.com and test2.company.com, and the two corresponding domains managed by the production (target) Active Roles instance are prod1.company.com and prod2.company.com.
To implement this scenario, complete the following steps:
- Create a list of the configuration objects to collect
- Create configuration data package
- Add domain mapping
- Deploy the configuration data package
Step 1: Creating a list of the configuration objects to package
In this step, you create a list of the configuration objects that you want to collect into the configuration package, and define how you want to collect their child objects.
To do that, create the selection.xml file, and save that file to the solution installation folder: <Active Roles installation folder>\Configuration Transfer Wizard\Scripts.
To clarify the file format, consider the following sample file that illustrates how to collect Access Templates, Managed Units, and Script Modules residing within specified containers:
<?xml version="1.0" encoding="utf-8"?>
<Configuration>
<include DN="CN=Common,CN=Access Templates,CN=Configuration" collectSelf="True" collectChildren="True"/>
<include DN="CN=Development,CN=Managed Units,CN=Configuration" collectSelf="True" collectChildren="False"/>
<include DN="CN=Priority Access,CN=Corporate Policy,CN=Script Modules,CN=Configuration" collectSelf="False" collectChildren="True"/>
</Configuration>
Step 2: Creating configuration data package file
In this step, you use the ARSconfig command-line tool to create a configuration data package file using the data from the selection.xml file created in Step 1.
To create the configuration data package file
- At a command prompt, navigate to the Configuration Transfer Wizard installation folder, and enter the following syntax:
Cscript.exe arsconfig.wsf /task:collect /selection:selection.xml
As the result, the package.xml configuration data package file will be created in the following default location: <Active Roles installation folder>\Configuration Transfer Wizard\Scripts.
Step 3: Configuring domain mapping
If the names of the managed domains are different in the test and production environments, you must add domain mapping that defines the correspondence between the domain names. When the configuration package is deployed in the target environment, the domain names specified as a part of the objects' attributes are replaced with the names of the production domains, according to the name mapping entries.
In this step, you create the CSV domain name mapping file—mapping.csv, and then save that file to the solution installation folder: <Active Roles installation folder>\Configuration Transfer Wizard\Scripts. In this scenario, the mapping.csv file contains the following lines:
"DC=test1,DC=company,DC=com","DC=prod1,DC=company,DC=com"
"DC=test2,DC=company,DC=com","DC=prod2,DC=company,DC=com"
Step 4: Deploying the configuration data package
In this step, you use the ARSconfig command-line tool to deploy the package.xml configuration package in the production Active Roles environment. When running the arsconfig.wsf script, specify the package file to deploy (package.xml), and the domain name mapping file (mapping.csv) you have created in Step 3.
To deploy the package
- At a command prompt, navigate to the Configuration Transfer Wizard installation folder, and enter the following syntax:
Cscript.exe arsconfig.wsf /task:deploy /package:package.xml /map:mapping.csv
Scenario: Rolling back the configuration changes
This step may be required if you have encountered any errors when deploying a configuration package in the production environment. By rolling back changes in the target configuration, you bring it to the state it was in before the package was deployed. Use the following instruction to roll back the changes made by the deployment of the package.xml file described in the scenario outlined above.
To roll back configuration changes
- At the command prompt, navigate to the Configuration Transfer Wizard installation folder, and enter the following syntax:
Cscript.exe arsconfig.wsf /task:rollback /package:package.xml
Known issues
This section provides a list of the currently known issues that customers may experience with Configuration Transfer Wizard. For each issue, the list includes an ID number, which identifies the issue, a brief description of the problem, and a workaround, if any exists, for the problem.
TF00004281
In the target Active Roles configuration, the solution cannot restore the edsvaDebuggingServer and edsvaDebuggingServerName properties of Script Module objects: those attributes are always empty.
WORKAROUND
Manually specify those properties with the use of the Active Roles console.
TF00004581
Configuration Deployment Wizard fails to deploy some of Access Templates. The solution log file contains the error message similar to the following text:
"Error [4710]: Administrative Policy returned an error. The object <Object DN> not found."
This error occurs if the source configuration contains nested Access Templates.
WORKAROUND
On the Collect Active Roles Configuration Data page of the wizard, select all the nested Access Templates you want to collect. If you are using ARSconfig, ensure that the selection file includes the nested Access Templates into the configuration export package.
TF00004585
After transferring a Policy Object that includes the “User Account Relocation Deprovisioning” policy entry, the “Description” and the “Error message returned by this policy” text boxes available on the User Account Relocation Policy Properties dialog box contain invalid target domain name.
WORKAROUND
After deploying the target configuration, manually edit those text elements using the Active Roles console.
TF00010732
When collecting Script Modules, Configuration Transfer Wizard may not collect the library Script Modules that are used by the Script Modules being exported. As a result, the deployment of the exported Script Modules may cause an error condition in the destination environment.
WORKAROUND
On the Collect Active Roles Configuration Data page of the wizard, select all the library Script Modules that are used by the Script Modules you want to collect. If you are using ARSconfig, ensure that the selection file includes the library Script Modules into the configuration export package.
TF00039803
When collecting Display Specifiers, Configuration Transfer Wizard may not collect the Active Roles virtual attributes for which the Display Specifiers are being exported. As a result, the deployment of the exported Display Specifiers may cause an error condition in the destination environment.
WORKAROUND
On the Collect Active Roles Configuration Data page of the wizard, select all the Active Roles virtual attributes for which the Display Specifiers are being exported. If you are using ARSConfig, ensure that the selection file includes the Active Roles virtual attributes into the configuration export package.
TF00050511
In a situation where an object to be exported does not exist in the source environment, Configuration Transfer Wizard stops the export process. As a result, the configuration export package may not include all objects that were selected for export.
WORKAROUND
Ensure that all objects you selected for export exist in the source environment.
TF00062463
Configuration Transfer Wizard does not provide the ability to export links that involve pre-defined or built-in objects, nor does it make possible to export pre-defined or built-in objects. As a result, you do not have the option to transfer, for example, the links of pre-defined Access Templates.
WORKAROUND
When transferring a configuration that includes any links of pre-defined or built-in objects, create the required links manually in the destination environment.
TF00125202
When using the Configuration Collection Wizard or Configuration Deployment Wizard, you may encounter an error message such as “A generic error occurred in GDI+.”
WORKAROUND
Disregard the error message. Click OK to close the error message box.
TF00130489
When using ARSconfig with the 'rollback' task option, you may encounter an error: “This script module is in use, and cannot be deleted.” This issue is most likely to occur with a PowerShell based Script Module containing a library script, and is due to the fact that the Script Module remains locked for a certain time period after all the Script Modules that use the library script have been deleted.
WORKAROUND
Run ARSconfig with the 'rollback' task option once more, or delete the Script Module manually, with the use of the Active Roles console.
TF00134074
With the display DPI setting of 'Large size (120 DPI)' you may encounter some minor visual defects on Configuration Transfer Wizard pages.
WORKAROUND
Use the display DPI setting of 'Normal size (96 DPI)'.
Understanding SPML Provider
Active Roles SPML Provider
Active Roles SPML Provider is designed to exchange the user, resource, and service provisioning information between SPML-enabled enterprise applications and Active Directory.
Active Roles SPML Provider supports the Service Provisioning Markup Language Version 2 (SPML v2), an open standard approved by the Organization for the Advancement of Structured Information Standards (OASIS). SPML - is an XML-based provisioning request-and-response protocol that provides a means of representing provisioning requests and responses as SPML documents. The use of open standards provides the enterprise architects and administrators with the flexibility they need when performing user management and user provisioning in heterogeneous environments.
