Administrative Reference

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Import/Export Utilities

This section provides detailed information about tools used to import/export data from the database:



The Policy Propagation Import/Export (policyIX) tool can be used to import and export policies and also export SSM configurations — it does not support importing SSM configurations. It is commonly used to move policy data from one database to another and to export an SSM configuration to an XML file for use when the SSM is deployed without an SCM.

Note: This section does not cover the use of policyIX for imports/exports between OES and Oracle Enterprise Repository. For that information, see Storing and Versioning Policy with Oracle Enterprise Repository in the Integration Guide.

SSL Requirements

To sign exported configuration files, PolicyIX uses the SSL infrastructure specified during the Administration Server installation, . Specifically, the policyIX.bat file invokes the tool with -Dales.policyTool.signer=wles-admin. The ales.policyTool.signer property is a required Java property that specifies the alias of the signing key in the identity keystore, which must be equal to the Administration server machine name.

The public key of the Administration Server is then retrieved from the SSL peer keystore for the purpose of validating the configuration file’s signature. This public key is available from the Administration Server’s certificate that was added to the SSL peer keystore during the enrollment process.

The unencoded signature of the XML file is stored in a corresponding signature file, whose name is derived from the full name of the signed XML file (including extension) with the added .sig extension. For example, myconfig.xml.sig.

After you export the configuration data, you must manually copy the XML configuration file and signature file to the SSM configuration directory, BEA_HOME/ales32-ssm/<ssm-type>/instance-name/config.

If you do not use the default name (wles.securityrealm.xml) for the configuration file, set the wles.realm.filename property in the SSM instance’s /config/ file. See the SSM Installation and Configuration Guide for additional information about the file.

Requirements and Limitations

Export an SSM Configuration

Use the following command to export an SSM configuration:

policyIX.bat <config_id> -exportConfig <config.xml> <exportfile.xml> -passwdPrompt

For example, the following command exports a SSM configuration named java2ssm to a file named java2ssmconfig.xml.

policyIX.bat java2ssm -exportConfig ..\config\policyIX_config.xml java2ssmconfig.xml

The name of the SSM configuration to be exported.
A static parameter required for exports.
The configuration file used by policyIX. For details, see PolicyIX Configuration File.
(Optional) The name of the file to contain the exported SSM configuration.
(Optional) When included in the command, you will be prompted for the password.
If not specified, the password must be specified in <config.xml>.

Export Policies

Use the following command to export policies from the database to an XML file:

policyIX.bat -export <config.xml> <exportfile.xml> -passwdPrompt

A static parameter required for exporting policies.
Configuration file used by policyIX. The <export_configuration>
element in this file specifies the policies and identities to export and the
product version of the SSM. See details, see export_configuration.
The name of the file that will contain the exported policies.
(Optional) When included in the command, you will be prompted for the password.
If not present on the command line, the password must be specified in <config.xml>.

Import Policies

Use the following command to load policies from an XML file to the database:

policyIX.bat -import -disableTransaction <config.xml> <importfile.xml> -passwdPrompt

A static parameter required for importing policies.
(Optional) Prevents loading of policies in a single transaction.
This is recommended when loading a large policy set. It improves loading performance, but loaded policy data will not be rolled back if the loading fails.
The configuration file used by policyIX. The <import_configuration> element
must specify how to handle policy duplicates. For details, see import_configuration.
This file will contain the policies to be imported. This is commonly a file that was exported for a database using policyIX.
If the file contains multi-byte characters, it must be must be UTF-8 encoded.
(Optional) When included in the command, you will be prompted for the password.
If not specified, the password must be specified in <config.xml>.

PolicyIX Configuration File

Table 3-1 describes the possible elements in the policyIX configuration file.

Table 3-1 Configuration File Elements
Parent element.
<policy_propagation xmlns:xsi=""
Child Elements:
Container element.
Child Elements:
import configuration
This is a container element that is used when the policyIX command includes the -export switch.
It’s child elements specify the policies and identities to export and the product version of the SSM.
Child Elements:
Specifies the object containing the policies to export.
You may specify one or more Organizations and/or Applications.
To export all policies under all applications in MyOrg:

<clipping_scope value="RootOrg!MyOrg"/>

To export all policies under the MyApp application:

<clipping_scope value="RootOrg!MyOrg!MyApp"/>

To export all policies under the App1 and App2 applications:

<clipping_scope value="RootOrg!MyOrg!App1,RootOrg!MyOrg!App2"/>

The scope can also be specified on the command line using the -clippingscope switch. This overrides the value specified in the configuration file.
policyIX.bat -export -withIdentity all -clippingScope RootOrg!MyOrg cfg.xml exp.xml
(Optional) Specifies what identities will be exported:

<withIdentity value="direct"/>

If not specified or the clipping scope is an application, no identities are exported.
direct = export all identities defined in the parent Organizaton
all = export identities defined in the parent Organizaton and those the Organization is inheriting.
This can also be specified on the command line using the -withIdentity switch. Using this switch overrides the value specified in the configuration file.
policyIX.bat -export -withIdentity all -clippingScope RootOrg!MyOrg cfg.xml exp.xml
Specifies the release version of the SSM that will use the exported configuration. This option is required

<target_ssm_version value="3.x"/>

2.x = ALES 2.x
3.x = ALES 3.0 and OES
This is a container element that is used when the policyIX command includes the -import switch. Its child element specifies how to handle policy duplicates.
Child Elements:
Specifies what to do when the database contains a duplicate policy.

<policy_load_procedure value="override"/>

override = add the policy without removing the existing policy
delete_existing = delete the existing policy before importing the policy.
This container element is used for all policyIX commands.
Its child elements specify how to connect to OES.
Child Elements:
The following name/value pairs that specify how to connect to OES.
server_property name="server_host_name" value="smysore02"/>
server_property name="server_port" value="7010"/>
server_property name="blm_server_port" value="7011"/>
server_property name="print_info" value="false"/>
server_property name="userID" value="admin"/>
server_property name="userPassword" value="password"/>
server_host_name = Machine name or IP address of admin server
server_port = Admin server port (default = 7010)
blm_server_port = BLM server port (default = 7011)
print_info = If set to true then policy propagation progress will be sent to standard console output
userID = the OES administrator user name (default = admin).
userPassword = the OES admin password (default = password). Not required if the policyIX command includes the -passwordPrompt switch
Container used when the policyIX command includes the -exportToALER or -importFromALER switch.
For information about OES to OER imports and exports, see Storing and Versioning Policy with Oracle Enterprise Repository in the Integration Guide.
Child Elements:
Name/value pairs that specify how to connect to Oracle Enterprise Repository.
<aler_property name = "server_version" value="3.0"/>
<aler_property name = "server_url" <value="http://localhost:7101/aler/services/FlashlineRegistry"/>
<aler_property name = "userName" value="admin"/>
<aler_property name = "userPassword" value="admin"/>
<aler_property name = "assetName" value="ALESPolicyAsset"/>
<aler_property name = "assetDescription" value = "export ALES to ALER"/>
<aler_property name = "importAssetVersion" value="1"/>
version = A OER server version of 3.0 or 2.6.
server_url = The URL for accessing the OER server.
userName = The user name to use to connect to OER.
userPassword = The user password of the above user.
assetName = The name of the asset to export/import.
assetDescription = (Optional) Asset description for an export
importAssetVersion = Asset version to import (required with, only valid if the -importFromAler switch)

XML Policy Data Files

When using policyIX to import policies, the policies to be imported must be specified in the required XML format. This section describes the required format and provides an example.

In addition to the information provided here, there are two ways understand the XML requirements:

Importing a Role Policy

The XML shown in Figure 3-1 could be used to import the following policies:

grant(//role/myrole, //resources/myresource, //MyOrg/MyDir/RJones/) if true;

grant( post, //myresource, //role/myrole/) if true;

Figure 3-1 Sample XML for Policy Imports

<?xml version="1.0" encoding="UTF-8"?>
<xb:policy_propagation xmlns:xb="">
    <xb:application_entry value="RootOrg!MyOrg!MyApp">
          <xb:resource_entry value="//resources/myresource"/>
          <xb:action_entry value="post"/>
          <xb:role_entry value="myrole" parent=""/>
            xb:policy_effect value="grant"/>
                <xb:policy_role_entry value="myrole"/>
              <xb:policy_resource_entry value="//resources/myresource"/>
             <xb:policy_user_entry name="RJones" directory="MyDir" scope="MyOrg"/>
           <xb:policy_effect value="grant"/>
               <xb:policy_action_entry value="post"/>
              <xb:policy_resource_entry value="//resources/myresource"/>
              <xb:policy_role_entry value="myrole"/>

Table 3-2 describes the XML elements used in the above example.

Table 3-2 XML Import Elements
Parent container
<xb:policy_propagation xmlns:xb="">
Parent container for all ALES policies.
When importing OES policies use <policy_propagation_data_v2>. When importing ALES 3.0 policies use <policy_propagation_data>.
Parent container for one or more organization_entry and application_entry elements.
Parent container for the application where the policies will be imported.
<xb:application_entry value="RootOrg!MyOrg!MyApp">
Specifies the resources being secured by the policy.
  <xb:resource_entry value="//resources/myresource"/>
This definition must include the initial //resources/ string followed by the resource hierarchy. Not required if the resources already exist.
Specifies the policy actions.
   <xb:action_entry value="post"/>
This is not required if the action already exists in the application.
Specifies roles used in the policy definition.
   <<xb:role_entry value="myrole" parent=""/>
Not required if the roles already exist. The parent= parameter must specify the role hiearchy.
This container element contains the policies to import and can include one or more <xb:membership_rule_entry> and <xb:authorization_policy_entry> elements.
Specifies a role policy to import.
   <xb:policy_effect value="grant"/>
    <xb:policy_role_entry value="myrole"/>
    <xb:policy_resource_entry value="//resources/myresource"/>
    <xb:policy_user_entry name="RJones" directory="MyDir" scope="MyOrg"/>
Specifies an authorization policy to import.
    <xb:policy_effect value="grant"/>
    <xb:policy_action_entry value="post"/>
    <xb:policy_resource_entry value="//resources/myresource"/>
     <xb:policy_role_entry value="myrole"/>

Modify Policy Propagation Servlet

By default, policyIX on WebLogic Server 8.15 supports the export of configuration data — but not policy data. This section describes how to manually modify the policy propagation servlet so that policyIX will also import/export policy data.

  1. Unpack the following WAR file:
  2. BEA_Home\ales32-admin\asiDomain\applications\asi.war
  3. Modify web.xml to include the following servlet and listener definitions:
  4. <listener>


  5. Rebuild asi.war with the updated web.xml file and update the stage file located in BEA_HOME/ales32-admin/asiDomain/asiAdminServer/stage/asiconsole/asi.war directory.
  6. Modify BEA_HOME/ales32-admin/config/WLESWebLogic.conf as shown below.
  7. Note: Entries you must add are shown in bold italics.

  8. Log in to the Administration Console and create a resource named policypropagation under the following existing resource:
  9. ASI/asiconsole/url/asi
  10. Add the following policy to grant POST, GET actions on the policypropagation resource:
  11. grant( [//priv/GET,//priv/POST], //app/policy/ASI/asiconsole/url/asi/policypropagation, //role/Everyone) if true;
  12. Open|bat in an editor and add the following java option:
  13. -Dadmin.server.type=wls81



Policyexporter is used to output data from the policy store to plain-text policy files. These policy files can be imported back to the same or to another policy store using the policyloader as described in Policyloader.

The plain-text policy files include the following management object types:

— Resources, resource attributes, and resource bindings
— Actions, action bindings, and action groups
— Roles
— Authorization and role policies
— Identities, including user, group, and membership
— Declarations, constants and evaluation functions
— SSM configuration data and providers' configuration data

The export process also generates two additional files (object_config, objattr_config) that contain SSM configuration data. These files also get loaded and are similar to object and objattr respectively in format. These files are split so as to differentiate policy elements from configuration elements. However, object_config and objattr_config can be merged into object and objattr respectively, if needed.

Requirements and Limitations

Observe the following requirements and limitations:

Performing a Policy Export

To perform a policy export using policyexporter:

  1. Set up a target directory in which to store the policy files.
  2. The directory name must contain no white space and cannot be not write-protected. The required free space depends on the size of the policy being exported.

  3. Make sure the database client is configured to connect to the database and that you have the access rights to perform an export.
  4. To perform an export, you must be a database administrator or the policy owner.

  5. Ensure that you can run the tools from the Administration Server’s /bin directory. These scripts need to locate files relative to this directory.
  6. Execute policyexporter.bat|.sh as described in Running Policyexporter.

Running Policyexporter

To run policyexporter, perform the following steps:

  1. Open a command window and change to the Administration Server’s \bin directory.
  2. Ensure that the current path (.) is included your PATH and that the client environment is set up properly.
  3. Run policyexporter.bat|.sh <directory>
  4. where <directory> is the full path to the target directory where the policy should be exported.




The Policy Import tool (policyloader.bat|sh) is a Java utility that can be used to import and export policy data. To import policies, it reads text files containing the policy definitions — each policy element is stored in a separate file, referred to as a policy file. For information on the specific format of these policy elements, see Advanced Topics in the Policy Managers Guide.

PolicyIX imports/exports support the following objects:

— Organizations and Identities
— Applications
— Resources and resource attributes
— Actions including action groups
— Declarations, including attribute definitions, evaluation functions, and constants.
— Roles, role hierarchies, role attributes
— Policies including Membership Rules and Authorization policies
— Resource binding
— SSM configuration (export only)
— Meta objects

Policyloader uses multi-threading processing and is optimized for fast imports and distribution of large policies. In addition, policy imports are transactional: all policies are loaded, or none.

Note: When running the Policy Import tool on a large policy, the number of records processed may not be synchronized. If multiple threads are used to import the data, when one thread completes before the other cannot be determined. If the threads are set too high, a message may appear indicating that the number of records processed is not synchronized. This is normal and is not a problem for the Policy Import tool.

Requirements and Limitations

Performing a Policy Import

To perform a import using policyloader:

  1. It is assumed that policy data files will be created by exporting policies from a database using the policyexporter utility as described in Policyexporter.
  2. In addition, policy data files may be manually created as described Advanced Topics in the Policy Managers Guide.

  3. Set up a configuration file to define your policy load. For instructions, see Policyloader Configuration File.
  4. You can use the ../examples/common/data/policy/template/load.conf file as a template.

  5. Run the tool as described in Running Policyloader.
  6. Check for errors in log file as described in Check for Errors.
  7. If necessary, rerun policyloader in -recover mode as described in Recover Mode.

Policyloader Configuration File

The configuration file consists of name/value pairs specifying information needed by policyloader. The file paths in the configuration file depend on the directory from which you run the Policy Import tool. You may use the full path filename to avoid directory dependency. Spaces are allowed between parameters and between new lines. Parameter names are case insensitive. Table 3-3 lists the parameters you need to configure for the Policy Import tool.

A sample file configuration file is shown in Policyloader Configuration File.

Table 3-3 Configuration Parameters 
The action to be performed. Supported values are LOAD and REMOVE (case insensitive).
REMOVE = Removes the policy from the database.
ADD = Loads the policy data into the database.
The application in the database that holds the administration policy (default = admin).
If commented out, the default value of admin is used.
Specifies the number of times retries should take place.
This can be used in the event the Administration server is still starting up when the import is being executed.
In most cases the Administration server is always running. Default: 100.
Specifies the amount of time (in milliseconds) to wait between context retries. DEFAULT: 10 (100 milliseconds)
The number of records to send at one time in a thread. Default: 200.
The optimal value is between 50 and 300.
Setting this value too high may slow the import process slows and also higher RequestTimeout and ConnectionTimeout values.
When there are multiple threads importing policy data, each processing a number of records, the number of records processed may result in an “out-of-sync” message.
However, it does not harm the data when importing the policy. The policy import tool switches to single thread when importing some policy elements, such as resources and declarations, as the later records have dependency on earlier records.
Specifies whether to hide console interaction or not (yes/no).
If you want to run the policy loader in the background as a batch process, set to no. Default: yes
no = Error messages are not displayed on the console and the user is requested to enter their Username and Password if they are missing in the configuration file.
yes = Error messages are displayed on the console.
This parameter must be enabled if you want to type in your password on the command prompt, rather then use the one specified in the password.xml or in the configuration file.
Specifies whether you want to log debug information. Default: 0
0 = Does not log debug information.
1 = Sends debug information to the file defined by: ErrorLogFile.
Always should be set to asi.
Specifies the name of error log file that will be generated if errors occur.
Default: error.log.
The mode of operation. Values are INITIAL or RECOVER (case insensitive). Use INITIAL mode the first time you run the Import Policy Tool to load a set of policy files. If you encounter errors in the initial load attempt, check the ErrorLogFile for a description of the error, correct the errors in the generated error file(s) (an error file is produced for each policy file that fails), and rerun the Import Policy Tool again, but this time in the RECOVER mode. This way the tool only attempts to load the generated error files. If the tool fails again, fix the errors, and run it again in RECOVER mode. Repeat until no errors are encountered.

Note: This parameter can also be passed in as a command-line parameter -recover or -initial. Values for this parameter on the command line override values specified in the configuration file.

The encrypted password file.
This file can be generated using the asipassword utility. For details, see xxxxx.
If this and the PasswordKeyFile parameters are not specified and console display is enabled, you will be prompted for these values.
The private key used to decrypt the password stored in the above file.
The directory from which to import policy files. For example: ../examples/policy. The path may be relative. Default: “.” (for relative)
Indicates if the policies should be flagged for distribution when imported into the database.
YES = flag the policies for distribution
NO = do not flag for distribition.
Policies flagged for distribution can be distributed using the administration console or the Entitlements Administration Application.
Specifies the time (in milliseconds) to wait for the server to respond. Should be longer for loading large files. May set to infinite (ASI.INFINITE) for very large files. Default: 600000
Number of threads running concurrently to process the policy import. The value depends on the capacity of the database server. Commonly, the optimal value is 2 - 4 or larger for a high capacity database server. Default: 3.
If set too high, performance may be slowed. The error logs will indicate this by database busy messages.
(Optional) The OES admin username (default = admin).
If not specified and ConsoleDisplay parameter is enabled, you will be prompted for this value.

Note: This user must have the privilege to import policy.

Sample Configuration File

Listing 3-1 provides sample configuration file.

Note: Be sure to use forward slashes (/) when specifying the policy file directory path.
Listing 3-1 Sample Configuration File
# Copyright (c) 2004-2008 Oracle and/or its affiliates. All rights reserved.

## In addition, is read in from the /config directory. Parameters set here will override values defined there.
#### Enterprise Domain Name (DEPRICATED - Should always be asi)
Domain asi
#### A OES admin user name. Must be the same as stored in database.
Username admin
#### Encrypted password file
PasswordFile C:/bea/ales32-shared/keys/password.xml
#### Password key file
PasswordKeyFile C:/bea/ales32-shared/keys/password.key
#### The application node holding the administration policy.
#### If commented out it assumes the dafult value of "admin".
ApplicationNode admin
#### Milliseconds to wait for server to respond. For large files 
#### increase or use ASI.INFINITE
RequestTimeout 600000
#### Number of times retries should take place(DEFAULT 100)
BLMContextRetries 10
#### Milliseconds to wait between retries (DEFAULT 100ms)
BLMContextInterval_ms 10000
#### Number of concurrent threads.
RunningThread 2
#### Number of entries loaded in a single load (200 here)
BulkSize 200
#### Directory of policy files. May be a relative path.
PolicyDirectoryPath C:/bea/ales32-admin/data/adminPolicy/standardBase
#### Indicate if policies should be distributed. Default = YES
PolicyDistribution flush
#### File where all error messages are logged.
ErrorLogFile C:/bea/ales32-admin/log/loader.log
#### Action to be performed: load or remove.  Default = LOAD
#Action REMOVE
#### Policy import mode: INITIAL or RECOVER. Default = INITIAL
#### This parameter can also be passed in as a command parameters.
#### Command line parameters override values in this file.
#### Uncomment to see debug information, default = 0 (no debug)
#Debug 1
#### Uncomment to hide console interaction (yes/no), default = yes
#### If you want to run loader in background/in batch process, set this to no
ConsoleDisplay no

Running Policyloader

Once the configuration file and the policy data files are set up, run policyloader follows:

  1. Execute: policyloader.bat|sh <load.conf>
  2. where <load.conf> is the name of the configuration file.

    You may also use the following options:

    Prevents loading of policies in a single transaction. This is recommended when loading a large policy set. It improves loading performance, but loaded policy data will not be rolled back if the loading fails.

    Print USAGE and exit.

    Run in initial mode (there should be no versioned files in the policy directory).

    Run in recover mode to revert to an earlier policy set. For details, see Recover Mode.

    (Default) Load policy from the files specified in the configuration file.

    Removes the policies from the database.

  3. Check for errors in log file.

Check for Errors

If an error occurs, the Policy Loader terminates; you must restart the Policy Import tool. The name of the error file is defined in the your Policy Import tool configuration file by the ErrorLogFile parameter. In addition, to distribute policy you need distribution privileges granted to you.

Also, because the Policy Import tool is multi-threaded and each thread writes out to the log when it is complete, you cannot guarantee the order in which each load completes.

The Policy Import tool processes policy files according to a predefined order, and if the policy file is not found, it tries to load the next policy file in the proper order. Records imported successfully are committed to the database. After the import process begins, you cannot go back within the same process and edit changes you have made. If you want to change what you have done, you have to start a new import process. After the import process is complete, you may run the removal operation to reverse the import process.

Recover Mode

When the policyloader encounters an error (other than Object Exists Error), it generates a file named <filename>.<version> (for example, object.1 , object.2) and logs an error message. These files contain only the problematic lines from policy data files. You can now correct the mistakes in these files and re-run the policy loader in the recover mode.

Recover mode can be run in one of two ways:

In recovery mode, policyloader will only try to load the highest version files that have not already been loaded. If you corrected priv.1 and there are still problems, then the loader will generate priv.2 with just the lines that failed. You can then correct priv.2 and rerun the policy loader in the recover mode. Perform additional iterations until policyloader does not generate any new version files and the error log file does not indicate any outstanding errors.



Loads the administrative policy that determines administrative access to access the Administration Console and Entitlements Administration Application. This utility is automatically called during the installation process and it is unlikely you will ever need to run it independently.





  Back to Top       Previous  Next