| Oracle® Role Manager Administrator's Guide Release 10g (10.1.4) Part Number E12029-02 |
|
|
View PDF |
| Oracle® Role Manager Administrator's Guide Release 10g (10.1.4) Part Number E12029-02 |
|
|
View PDF |
This chapter provides procedures for initial load of data into Oracle Role Manager. The data loader can be used to load new objects or update existing objects in 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 best determine the appropriate approach to 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:
Normally in CSV format (although any character delimiter is supported), data files contain the actual data to load into Oracle Role Manager.
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 BL definitions. Load procedures are a clean representation of the default load operations, uncluttered by the system-level details contained in the BL definitions.
Business logic (BL) definitions
The BL definitions contain detailed procedures representing the default loadable objects, attributes, and relationships and the XML mapping to BL Plug-ins for business operations called by the loader request.
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.
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.
All data loaded into Oracle Role Manager enters through the business logic layer to be imported correctly. This is enforced by having the object definitions in the load procedures match those in the BL definition files. For example, the BL definition for the person object contains the same or 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. (Refer to Section 3.4.2 for information about the Oracle Role Manager standard defaults.)
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:
zip -f 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 is 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 prevent the users to view the administrator's password, Oracle recommends you to create a custom system identity and grant them a custom system role that has been granted the absolute minimum system privileges, necessary to load the data that they will be loading. 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 using a 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.If you're not sure how to determine which process your load will require, you can analyze the default loader components provided in Oracle Role Manager. 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, will need to extract them from an archive file. 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_install>/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.
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 contain all the predefined, default load operations available for use in load requests (see Table 3-1) that can be used to create objects and the relationships between those objects. The load procedures also contain the superset of all possible attributes to load per object type.
Table 3-1 Default Load Procedures in the Standard Model
| Operation | Description | File Parser |
|---|---|---|
|
addManagerToPersonHiearchy |
Creates a relationship between a manager and a person and requires the following attributes:
|
person_manager_script |
|
addPersonToReportingHiearchy |
Creates a relationship between a person and a reporting hierarchy (organization in the reporting hierarchy) and requires the following attributes:
|
reporting_person_script |
|
addOrgHeadToOrganization |
Creates a relationship between an organization head and the organization and requires the following attributes:
|
organization_head_script |
|
addToCostCenterHierarchy |
Creates a relationship between an organization and the cost center hierarchy and requires the following attributes:
|
cost_center_script |
|
addToLocationHierarchy |
Creates a relationship between an organization and the location hierarchy and requires the following attributes:
|
location_script |
|
addToReportingHierarchy |
Creates a relationship between an organization and the reporting hierarchy and requires the following attributes:
|
reporting_script |
|
createApprover |
Creates an Approver Role with the following attributes:
|
approver_script |
|
createApproverRoleGrant |
Grants an Approver Role to a person with the following attributes:
|
approver_role_grant_script |
|
createBusinessRole |
Creates a Business Role with the following attributes:
|
business_role_script |
|
createBusinessRoleGrant |
Grants a Business Role to a person by creating a role grant relationship with the following attributes:
|
business_role_grant_script |
|
createBusinessRoleToItRoleMapping |
Maps a Business Role to an IT Role by creating a relationship with the following attributes:
|
business_to_itrole_script |
|
createITRole |
Creates an IT Role with the following 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. |
it_role_script |
|
createITPrivilege |
Creates an IT Privilege with the following attributes:
|
it_privilege_script |
|
createITRoleGrant |
Grants an ITRole to a person by creating a role grant relationship with the following attributes:
|
it_role_grant_script |
|
createITRolePrivilegeMapping |
Maps an IT Role to an IT Privilege by creating a relationship with the following attributes:
|
itrole_to_privilege_script |
|
createOrganization |
Creates an Organization with the following attribute:
|
organization_script |
|
createPerson |
Creates a
|
person_script |
|
createOrganizationalUnit |
Creates an Organizational Unit with the following attribute:
|
organizational_unit_script |
|
createSystemRole |
Creates an System Role with the following attributes:
|
system_role_script |
|
createSystemRoleGrant |
Grants a System Role to a person by creating a role grant relationship with the following attributes:
|
system_role_grant_script |
|
createSystemRolePrivilegeMapping |
Maps a System Role to a System Privilege by creating a relationship with the following attributes:
|
systemrole_to_privilege_script |
Note:
Refer to the
standard.xml file to see constraint information for each attribute in these load operations.Example 3-8 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>
The business logic (BL) definitions further define the allowable operations that can be invoked by the 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-1) 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-9 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. This 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 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-10 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>
Load requests are what specify 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-11 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-2.
Table 3-2 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 |
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 |
|
loadITRoleGrants |
it_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.You can upload a DAR file to load data of maximum size one byte into the system. If you try to load data larger than this maximum upload size, you get an error message. You can configure the maximum data upload size to a higher or lower value than the default.
For WebLogic Server
To configure the data upload 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>
For JBoss Server
To configure the data upload 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>
For WebSphere Server
To configure the data upload 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.
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, contain actual data to load into Oracle Role Manager. Data files can use any character as a delimiter if it's 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.
Note:
Make sure 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 but contain no data.
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.
Abandoned transactions are those pending transactions which have seen no activity in a configurable time-to-live period. The transactions are abandoned either because of a network problem between Role Manager client and server or the user of Role Manager navigates away from the transaction page without completing the transaction. Role Manager uses a configurable scheduled task to cleanup such abandoned transactions. The following factors are considered to cleanup the abandoned transactions:
Any pending transaction that has no activity within the time-to-live window is eligible for cleanup. However, the actual cleanup only occurs when the scheduled task for cleanup is run.
An excessively short time-to-live window will interfere with normal user activities. Therefore Oracle recommends a time-to-live value of at least 1 hour.
You can consider these two factors to configure the scheduled task. The default time at which the scheduled task is set to run is 1 a.m. and time-to-live value is 1 hour. These values can be set by unpacking the configurations.car file and editing the oracle.iam.rm.timer.abandonedTransactionCleanupTimer.xml file. The following is the default configuration file:
<?xml version="1.0" encoding="UTF-8"?>
<timer-config xmlns="http://xmlns.oracle.com/iam/rm/timer/config/1_0">
<job-configs>
<job-config>
<factory-classname>oracle.iam.rm.bizxact.impl.AbandonedTransactionCleanupFactory</factory-classname>
<job-id>AbandonedTransactionCleanupJob</job-id>
<group-id>TransactionGroup</group-id>
<parameters>
<parameter>
<id>timeToLive</id>
<integer>60</integer> <!-- hourly, represented by minute-granularity -->
</parameter>
</parameters>
<singleton>true</singleton>
<!--
The default invocation interval is 0 0 1 * * ?
This cron-style expression translates to 1:00 AM every day.
Refer to the Oracle Role Manager Administrator's Guide for more information.
-->
<cron>
<cron-expression>0 0 1 * * ?</cron-expression>
</cron>
</job-config>
</job-configs>
</timer-config>
