| Oracle® Role Manager Administrator's Guide Release 10g (10.1.4.2) Part Number E14610-01 |
|
|
View PDF |
| Oracle® Role Manager Administrator's Guide Release 10g (10.1.4.2) Part Number E14610-01 |
|
|
View PDF |
This chapter provides procedures for initial load of data into Oracle Role Manager. The data loader can be used to load data into the system. For information about implementing special processing as part of a load procedure, contact your Oracle Consulting Services representative.
This chapter assumes you have deployed the standard data model provided with Oracle Role Manager or a custom model built on the standard model. It also assumes that you understand the business requirements associated with the data that must be loaded into Oracle Role Manager.
It contains the following topics:
To determine the best approach for loading data into Oracle Role Manager, it is important to understand the overall load process along with the sample scripts and procedures provided with Oracle Role Manager.
The overall load process of data into Oracle Role Manager (see Figure 3-1) involves the following components:
Load request
The load request defines which load procedures should run as part of the data load. This file also specifies the order for loading objects in the required sequence.
Normally in CSV format (although any character delimiter is supported), data files contain the actual data to load into Oracle Role Manager. For more information about data files, refer "Load Requests".
Note:
Oracle does not recommend you to use Microsoft Excel to edit the CSV file, because it inserts extra quotes when you insert double quotes in the file.Load procedures contain the object creation and relationship creation procedures that map to the Business Logic (BL) definitions. Load procedures are a clean representation of the default load operations, uncluttered by the system-level details contained in the BL definitions. For more information about load procedures, refer "Default Loader Procedures (Standard Model)".
Business logic definitions
The BL definitions contain detailed procedures representing the default loadable objects, attributes, and relationships and the XML mapping to Business Logic Plug-ins for business operations called by the loader request. For more information about Business Logic Plug-ins, refer "Business Logic Plug-ins". For information about car file, refer to Step 4 of "Loading Data From an External Database".
File parsing scripts
These scripts contain mappings to load procedures and the load sequence of input parameters (attributes) within the load operation relative to object type. This commonly includes only a subset of the object's attributes into which to load data.
All data loaded into Oracle Role Manager is processed by the BL layer to ensure that various constraints are enforced at load time. For example, IT roles in Oracle Role Manager only gain membership through business role mappings. This is enforced by having the object definitions in the load procedures match those in the BL definition files. Another example is that the BL definition for the person object contains either the same or a superset of attribute definitions as those included in the createPerson load procedure.
If you have data to load into custom object definitions or custom attributes, you will need to add new business logic and load procedures.
Before loading data, there are three questions you should ask to help identify the approach to take in loading your data:
Does the deployed data model contain all the object types and attributes you want to load?
Do the standard load procedures for each of your object types contain all of the operations you need?
Do the load operations in file parsing scripts for each of your object types contain all of the attributes you want to load?
The following three examples describe the possible business scenarios around initial data loads into Oracle Role Manager. Choose the most suitable scenario, which will identify the steps that you will need to follow. (For information about the Oracle Role Manager standard defaults, refer "Default Loader Procedures (Standard Model)".)
For each of these examples, you can refer to Figure 3-1 to help visualize the load process flow for your deployment of Oracle Role Manager.
Example 3-1 The data you want to load already maps to the standard data model and standard load procedures.
The standard data model and the file parser scripts must contain all the object types and attributes that you want to load and there are no model changes required to load your data set.
Even if your business model requires data model extensions, because you don't need to load data into the extended schema, you can still use the sample scripts.
This example requires the following steps:
Create load request.
Prepare data files.
Bundle and upload data with request.
Example 3-2 The standard data model supports the data you want to load, but the attributes in file parser load scripts aren't what you want.
In other words, the mismatch is only in the way the file parser script orders or maps the subset of attributes for a particular of multiple object types. For example, if the person file parser script maps six attributes for person data and you want to load twelve attributes.
As in Example 3-1, if the data model has been extended but the data you want to load is not part of the custom model, fewer components are involved in the load process.
This example requires the following steps:
Create new file parser scripts from existing sample scripts.
Bundle and deploy new configuration.
Create load request.
Prepare data files.
Bundle and upload data with request.
Example 3-3 The data to load must go into a custom model.
Whether your data model extensions into which you want to load data are an added attribute or a new object type, loading data into a custom model requires supporting business logic and new process definitions.
This example assumes the data model has already been extended and requires the following steps:
Create BL definitions.
Create load procedures.
Create file parser scripts.
Bundle and deploy new configuration.
Create load request.
Prepare data files.
Bundle and upload data with request.
You can load the data into Role Manager from an external database by performing the following steps:
Write an SQL query to select the data that you want to load into Role Manager. Your query should return all attributes that Role Manager requires for the kind of object being loaded. Assign a name to each column of the query returned. The following is an example query that returns the required attributes for Role Manager PERSON objects:
Define a data source that your application server can use to execute queries. The procedure for doing this varies from one application server to the other.
Create a load script that will execute your query and return query results to the appropriate Role Manager task.
For example a load script named persondb_script.xml creates a procedure named loadPersonsFromDB. The version of the script and its dependencies are declared. In this case the business logic dependency was copied from another load script. If you go through several iterations of the script while debugging, it is important to increment the version number whenever the script is changed. When deploying the script, the new version number signals Role Manager that any previous versions are obsolete. If the version number is not incremented, then the deploy task exits without deploying the new script.
Note:
In the input-params section of the script columns in the query's result set are mapped to the parameters of the createPerson procedure.
Example 3-5 Load Data
<!-- persondb_script.xml --> <?xml version="1.0" encoding="UTF-8"?> <load-script xmlns="http://xmlns.oracle.com/iam/rm/loader/script/1_0" xmlns:t="http://xmlns.oracle.com/iam/rm/type/def/1_0" id="persondb_script" version="10.1.4.6"> <dependencies> <business-logic-dependency def-id="bizlogic.sample" version="10.1.4.1"/> </dependencies> <procedures> <procedure id="loadPersonsFromDB"> <operations> <database-load id="database" datasource="java:/ExternalDS" query-sql="select 'A000002' as id, 'John' as first_name, 'Smith' as last_name, 'John Smith' as display_name, 'active' as status from dual"> <procedure-call id="call" procedure-id="createPerson" script-id="procedures"> <input-params> <column name="givenName" column-name="first_name"><t:string-ext/></column> <column name="sn" column-name="last_name"><t:string-ext/></column> <column name="displayName" column-name="display_name"><t:string-ext/></column> <column name="uniqueName" column-name="id"><t:string-ext/></column> <column name="status" column-name="status"><t:string-ext/></column> </input-params> </procedure-call> </database-load> </operations> </procedure> </procedures> </load-script> <!-- end persondb_load.xml>
Deploy the load script. You can do this by creating a car file that contains just the script(s) that loads the external data. First put the load script in a directory with the path name that loader expects (config/oracle.iam.rm.loader). A test directory (test_dbload) was used to isolate this experiment from the Role Manager installation:
test_dbload\config\oracle.iam.rm.loader
To create the car file:
Change to the parent of the config directory (test_dbload). Use zip to create the car file:
jar -cvf test_dbload.car config
Copy testdb_load.car to the ORM_HOME/config directory.
Make sure the appserver has been stopped and then deploy the new car file using ORM_HOME/bin/deploy.bat:
deploy.bat "..\config\test_dbload.car" ormowner ormuser admin
Create a load request that calls the loadPersonsFromDB procedure. Example 3-6 calls "persondb_script" and "loadPersonsFromDB". No parameters are required for this load, but it seems that a parameter section is required even if it is empty. The ordering mode ("trusted-sequential") was copied from another load script.
Example 3-6 Load Request
<!-- load-request.xml --> <?xml version="1.0" encoding="UTF-8"?> <load-request xmlns="http://xmlns.oracle.com/iam/rm/loader/data/1_0" load-script-id="persondb_script" procedure-id="loadPersonsFromDB" ordering-mode="trusted-sequential"> <parameters> </parameters> </load-request>
Create a DAR file to contain the load request. Use zip to create the dar file:
zip dbtest.dar load-request.xml
Load the data by performing the following steps:
Start the application server.
Open ormconsole in a web browser and click Upload.
Enter the username and password for the admin user and browse for dbtest.dar.
Click Load.
The load.sh file is designed to allow loading DAR files in the Role Manager console in a command-line pattern. Using this feature, you can load DAR files automatically. The following is the command used to load the DAR file:
load.bat server_url dar_file orm_username
An example for this command is:
load.bat http://localhost:8080/ ../data/my_people.dar admin
When you execute this command, the password for the administrator user is prompted. If you are loading the DAR file automatically, you can avoid the password prompt using the following command:
load.bat http://localhost:8080/ ../data/my_people.dar admin/admin123
Running the automated load process may raise a security issue. This is because, users with access to the computer running the tool can see the administrator's password in the process list. To avoid compromising, Oracle recommends that you create a custom system identity for data loading and grant that identity a role configured with the minimum system privileges for the data to be loaded. The following example illustrates this scenario.
Example 3-7 Loading Data With Custom System Identity
Assume that the command-line tool is only used for loading people as part of reconciliation process. The system identity used for the tool must be able to run the person reconciliation business operation. To enable this and to limit the impact of this user's credentials being exposed, perform the following:
Create a new permission called "reconcile" and associate it with the person object type.
Create a new business operation for the person attribute reconciliation and assign "reconcile" privilege on person.
Create a new loader script that invokes the new business operation.
Create a new system role and associate it with the new "reconcile person" privilege.
Create a new system identity and grant the new system role to it. For more information about system identity, refer to Chapter 4.
The newly created system identity can now only be used to load person details to be reconciled.
Note:
The system identity created for loading person details to be reconciled cannot be used for loading anything other than person details.The default loader components can be used to understand the data loading process. This section describes these components in more detail and shows you where to find the scripts that you will either use by default or use as starting places, should you need to create new ones.
It may be useful to familiarize yourself with the standard data model along with any schema extensions that are planned or already deployed.
In this section:
To view the sample loader scripts and procedures, you will need to extract them from the archive files provided in your Oracle Role Manager installation. You may want to refer to these file on an ongoing basis or you may want to use them for convenience as a starting place for your customized load processes.
To get the sample loader scripts and related files:
On the Oracle Role Manager installation host, navigate to ORM_HOME/config.
Using an utility like WinZip or gunzip, extract the entire contents of standard.car into a temporary location.
In the temporary location used to extract the files, navigate to config/oracle.iam.rm.loader.
These are copies of the files that are used when running the standard data procedure.
From the same location, navigate to config/oracle.iam.rm.bizlogic.def.
You will see the bizlogic.loader.xml file that is referenced when running the standard data procedure.
From the same location, navigate to config/oracle.iam.rm.temporal.
You will see the standard.xml file that represents the data model supporting the loader and the Oracle Role Manager Web UI.
These can be modified and used as a starting place for custom procedures.
Load requests specifies which load operations to run for a particular data load, while mapping the load operations to data files bundled with the load request in a DAR file (data archive).
Example 3-8 Load Request
<load-request load-script-id="reporting_script" procedure-id="buildReportingHierarchy">
<parameters>
<resource-ref name="reporting_file">
<resource-path>reporting.txt</resource-path>
</resource-ref>
</parameters>
</load-request>
Load requests must be contained in a single file to ensure the operations are run in the correct sequence. The supported sequence of operations is shown in Table 3-1.
Table 3-1 Required Sequence of Load Operations
| Operations in Sequence | File Parser |
|---|---|
|
Roles |
|
|
loadBusinessRoles (Maps first to the data file containing the business roles, then to membership rules data, and finally to eligibility rules data.) |
business_role_script |
|
loadSystemRoles |
system_role_script |
|
loadITRoles |
it_role_script |
|
loadApprovers |
approver_script |
|
loadITPrivileges Note: Although in the user interface, the term |
it_privileges_script |
|
loadITRolePrivilegeMappings |
itrole_to_privilege_script |
|
loadSystemRolePrivilegeMappings |
systemrole_to_privilege_script |
|
loadBusinessRoleToItRoleMappings |
businessrole_to_itrole_script |
|
Organizations |
|
|
loadOrganizationsWithParents |
organization_script |
|
loadOrganizationalUnitsWithParents |
organizational_unit_script |
|
loadPersons |
person_script |
|
buildPersonReportingHierarchy |
reporting_person_script |
|
buildLocationHierarchy |
location_script |
|
buildCostCenterHierarchy |
cost_center_script |
|
buildReportingHierarchy |
reporting_script |
|
RoleGrants |
|
|
loadBusinessRoleGrants |
business_role_grant_script |
|
loadSystemRoleGrants |
system_role_grant_script |
Note:
Relationships between objects cannot be created until those objects already exist, so depending on these relationships, sequence can be an important relative to the business logic of the load operations.The file parsing scripts determine which attributes to load and in what order. The matching data files must use the same order. It is recommended that there be a single parsing script for each entity type.
In the following example, note the input parameters in the operations section. This is where the order is specified.
Example 3-9 File Parser (reporting_script)
<?xml version="1.0" encoding="UTF-8"?>
<load-script xmlns="http://xmlns.oracle.com/iam/rm/loader/script/1_0"
xmlns:t="http://xmlns.oracle.com/iam/rm/type/def/1_0"
id="reporting_script" version="10.1.4">
<dependencies>
<script-dependency script-id="procedures" version="10.1.4"/>
</dependencies>
<procedures>
<procedure id="buildReportingHierarchy">
<input-params>
<input-param name="reporting_file">
<t:binary>
<t:non-null-constraint id="non-null">
<t:violation-message>The binary must be provided.</t:violation-message>
</t:non-null-constraint>
</t:binary>
</input-param>
</input-params>
<operations>
<file-load id="file" file-param="reporting_file">
<string-tokenizer string-delimiter="^" token-separator=",">
<data-events>
<data-event id="add_reporting">
<procedure-call id="call" procedure-id="addToReportingHierarchy" script-id="procedures">
<input-params>
<token name="child-name" index="0"><t:string-ext/></token>
<token name="parent-name" index="1"><t:string-ext/></token>
</input-params>
</procedure-call>
</data-event>
</data-events>
</string-tokenizer>
</file-load>
</operations>
</procedure>
</procedures>
</load-script>
The business logic (BL) definitions further define the allowable operations that can be invoked by load requests. These definitions, in a single XML file (bizlogic.loader.xml), contain the same operations as those in the load procedures file (see Table 3-2) yet also include further details such as:
Load confirmation text and argument mappings used for audit messages
The plug-in configuration containing the ID used to execute the load operation
Example 3-10 Plug-in Configuration (addToReportingHierarchy)
<snapshot-logic-definition plugin-pack-id="oracle.iam.rm.bizlogic.plugin.standard_ext" plugin-id="add_to_hierarchy">
<ext config-version="1.0">
<config>
<![CDATA[
<add-to-hierarchy xmlns="http://xmlns.oracle.com/iam/rm/bizlogic/plugin/standard_ext/1_0"
hierarchy-type="reportingHierarchy" parent-id-attribute-name="reportingOrg_id"
root-id-attribute-name="reportingHierarchyRoot_id">
<attributes>
<attribute attribute-id="child-name" argument-id="child-name"/>
<attribute attribute-id="parent-name" argument-id="parent-name"/>
</attributes>
</add-to-hierarchy>
]]>
</config>
</ext>
</snapshot-logic-definition>
In the preceding example, the plug-in ID is add_to_hierarchy and the configuration specifies the hierarchy type and the relationship paths, which allows that the Java plug-in class that handles this operation can be used for adding any object to any hierarchy, if it's supported by the schema.
The default loader procedures, in a single XML file (procedures.xml), provide a convenient view into the standard data model as it relates to the default load operations. This file maps procedures to the business logic operations that can be called by load requests.
The load procedures define data loading operations that will be called in a load request (see Table 3-2) that can be used to create objects and relationships between those objects. The load procedures also illustrate data loading for all the attributes and object types in the standard data model. Example 3-11 illustrates procedure for data loading operation, addToReportingHierarchy defined in the definition-id, bizlogic.loader.
Example 3-11 Load Procedure (addToReportingHierarchy)
<procedure id="addToReportingHierarchy">
<input-params>
<input-param name="child-name">
<t:string>
<t:length id="length" max-length="256">
<t:violation-message>The organization's name can be no longer than 256 characters.</t:violation-message>
</t:length>
</t:string>
</input-param>
<input-param name="parent-name">
<t:string>
<t:length id="length" max-length="256">
<t:violation-message>The parent's name can be no longer than 256 characters.</t:violation-message>
</t:length>
</t:string>
</input-param>
</input-params>
<operations>
<business-transaction-operation id="add_to_reporting_hierarchy" definition-id="bizlogic.loader" operation-id="addToReportingHierarchy">
<input-params>
<param name="child-name" param-name="child-name"> <t:string-ext/></param>
<param name="parent-name" param-name="parent-name"> <t:string-ext/></param>
</input-params>
</business-transaction-operation>
</operations>
</procedure>
Note:
For File Parser definitions, refer to the oracle.iam.rm.loader file in the following location:ORM_HOME/config/standard.car/config/oracle.iam.rm.loader
Table 3-2 Default Load Procedures in the Standard Model
| Operation | Description | Attributes | File Parser |
|---|---|---|---|
|
addManagerToPersonHiearchy |
Creates a relationship between a manager and a person. |
This operation requires the following attributes:
Note: The default procedure identifies the person and the manager by their email attributes. If your data file contains the |
person_manager_script |
|
addPersonToReportingHiearchy |
Creates a relationship between a person and a reporting hierarchy (organization in the reporting hierarchy). |
This operation requires the following attributes:
|
reporting_person_script |
|
addOrgHeadToOrganization |
Creates a relationship between an organization head and the organization. |
This operation requires the following attributes:
|
organization_head_script |
|
addToCostCenterHierarchy |
Creates a relationship between an organization and the cost center hierarchy. |
This operation requires the following attributes:
|
cost_center_script |
|
addToLocationHierarchy |
Creates a relationship between an organization and the location hierarchy. |
This operation requires the following attributes:
|
location_script |
|
addToReportingHierarchy |
Creates a relationship between an organization and the reporting hierarchy. |
This operation requires the following attributes:
|
reporting_script |
|
createApprover |
Creates an Approver Role with the attributes. |
This operation requires the following attributes:
|
approver_script |
|
createApproverRoleGrant |
Grants an Approver Role to a person with the attributes. |
This operation requires the following attributes:
|
approver_role_grant_script |
|
createBusinessRole |
Creates a Business Role with the attributes. |
This operation requires the following attributes:
|
business_role_script |
|
createBusinessRoleGrant |
Grants a Business Role to a person by creating a role grant relationship with the attributes. |
This operation requires the following attributes:
|
business_role_grant_script |
|
createBusinessRoleToItRoleMapping |
Maps a Business Role to an IT Role by creating a relationship with the attributes. |
This operation requires the following attributes:
|
business_to_itrole_script |
|
createITRole |
Creates an IT Role with the attributes. If you have deployed the data model extensions for the integration with Oracle Identity Manager, additional attributes can also be loaded. Refer to the Oracle Role Manager Integration Guide for Oracle Identity Manager for more information. |
This operation requires the following attributes:
|
it_role_script |
|
createITPrivilege Note: Although in the user interface, the term |
Creates an ITPrivilege with the attributes. |
This operation requires the following attributes:
|
it_privilege_script |
|
createITRolePrivilegeMapping |
Maps an IT Role to an IT Privilege by creating a relationship with the attributes. |
This operation requires the following attributes:
|
itrole_to_privilege_script |
|
createOrganization |
Creates an Organization with the attributes. |
This operation requires the following attributes:
|
organization_script |
|
createPerson |
Creates a |
This operation requires the following attributes:
|
person_script |
|
createOrganizationalUnit |
Creates an Organizational Unit with the attribute. |
This operation requires the following attributes:
|
organizational_unit_script |
|
createSystemRole |
Creates a System Role with the attributes. |
This operation requires the following attributes:
|
system_role_script |
|
createSystemRoleGrant |
Grants a System Role to a person by creating a role grant relationship with the attributes. |
This operation requires the following attributes:
|
system_role_grant_script |
|
createSystemRolePrivilegeMapping |
Maps a System Role to a System Privilege by creating a relationship with the attributes. |
This operation requires the following attributes:
|
systemrole_to_privilege_script |
Note:
Refer to thestandard.xml file to see constraint information for each attribute in these load operations.By default the largest DAR file you can load is 10MB, loading a larger file results in an error. You can configure the maximum DAR file size using the following instructions.
For WebLogic Server
To configure the DAR file size for WebLogic server:
Go to Environment, Servers, ORM Server.
On the Configuration tab, click the Server Start subtab.
In the Arguments field, append the following argument to the new value.
-Doracle.iam.rm.loader.max_upload_size=<new value>
Restart the WebLogic application server.
For JBoss Server
To configure the DAR file size for JBoss server:
Edit the config file:
JBOSS_HOME/bin/run.bat
Add the following argument to JAVA OPTS:
-Doracle.iam.rm.loader.max_upload_size=<new_value>
Restart the JBoss application server.
For WebSphere Server
To configure the DAR file size for WebSphere server:
Go to Servers, Application Servers, ORM Server.
In the Server Infrastructure section, expand Java and Process Management, and then click Process Definition.
In the Additional Properties section, click Java Virtual Machine, and then click Custom Properties.
Click New and enter the following information:
In the Name field, type oracle.iam.rm.loader.max_upload_size.
In the Value field, type the maximum size of data upload that you want to set, for example, 2 byte.
In the Description field, type the description for the maximum upload size that you set, for example, maximum size limit for the Oracle Role Manager loader.
Click Ok.
Restart the WebSphere application server.
The data files that you bundle with the load request must match the file names specified in the load request.
Data files, normally text files in comma-separated (",") format and string delimiter for all object types in caret ( "^") format, contain actual data to load into Oracle Role Manager. Data files can use any character as a delimiter if it is set as the token-separator attribute in the script. The order of data, separated by the delimiter (with no spaces) must match the order of the input parameters in the respective file parsing script.
It is recommended that you separate the data files by type of entity and relationship to have enough flexibility to load them in the correct sequence.
To prepare your data files, bundle them with the load request as a DAR (data archive) file as follows:
In a command window, change to the directory containing the loader-request.xml file and other data files.
Run the following command:
zip -r custom _data.dar
Note:
Ensure the loader request refers to data files that exist. For example, your person data file might have a different file name thanperson.txt, the sample person data file.Initiating the load process involves several steps to prepare the archive files expected by the loader. In addition, the Oracle Role Manager server must be running on the application server. (Refer to the Oracle Role Manager Installation Guide for more information.)
To run the loader:
If you have customizations:
Make sure that the Oracle Role Manager users/schemas exist on the database.
Create a CAR file (configuration archive with .car extension) containing the new BL definitions, load procedures or file parsing scripts.
Deploy the configuration using the procedure described in Section 2.3.
Create a DAR file (data archive with .dar extension) containing the data files with the loader request file.
Deploy the Oracle Role Manager server to your application server as described in the Oracle Role Manager Installation Guide.
In a web browser, go to the application server host and port used for the Oracle Role Manager data loader. For example:
http://<host>:8080/ormconsole
Type the user name and password of the administrator who has the appropriate permissions to import data into Oracle Role Manager.
Click Browse to navigate to the newly create DAR file, then click Load.
The page will display the progress of your data load. You can click refresh at any time to refresh the page.
|
 Copyright © 2008, 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|