| Oracle® Role Manager Developer's Guide Release 10g (10.1.4) Part Number E12759-01 |
|
|
View PDF |
| Oracle® Role Manager Developer's Guide Release 10g (10.1.4) Part Number E12759-01 |
|
|
View PDF |
This chapter describes the steps to modify the data model configuration of the Oracle Role Manager data model in a managed fashion.
Note:
This chapter assumes that an instance of Oracle Role Manager is already installed following the instructions in the Oracle Role Manager Installation Guide.This chapter includes the following sections:
Caution:
Data model changes cannot be reverted. Before making any modifications to the Oracle Role Manager data model, be sure to back up both of the Oracle Role Manager schemas (owner and application user schema) so that you can revert to the original state.There are several approaches to customizing the Oracle Role Manager data model, depending on the type of customization that you want.
The data model is configurable through XML files. Oracle Role Manager provides a standard data model, which creates and configures the entities required by the Oracle Role Manager application. The first thing to determine is whether your customizations require modifications to the standard model or additions to the standard model.
If the standard model has already been deployed and you need to make changes, it is recommended that you copy the standard configuration, edit it, then deploy your changes to the database. In this case, it is recommended that the deployment of the modified standard model is deployed on an empty schema because some definitions, such as constraints on attributes, cannot be additive. If you are certain that your changes are only additive and do not affect constraints, you can deploy your customizations over an existing deployment of the standard model.
Note:
If you are using the Oracle Role Manager application's user interface, you should take care not to modify any entities or attributes in a way that would make the application unusable. Examples of this are removing the
organization or location hierarchy entities.If you are adding attributes on entities that are already in the standard model or new entities with new definitions, you can create a new XML file and deploy just those additions.
The standard model depends on the primordial model, which defines the core entities required for Oracle Role Manager to function.
Both the standard and primordial models are described in detail in Chapter 1. Although all the object types and constraints are described in that chapter, it is helpful to be aware of how those object types are defined in the XML file while determining the customization approach you want to take.
Note:
The primordial model is not customizable.To view the standard configuration, you will need to extract files from the standard.car configuration archive.
To view the standard model configuration:
On the Oracle Role Manager host, navigate to the ORM_HOME/config directory:
Using a utility like WinZip or jar, extract the entire contents of standard.car into a temporary location, such as ORM_HOME/config_temp.
Once expanded, notice that in your temporary location, there is the config directory, and in that, the subdirectories for the standard configuration. The subdirectory and files the pertain to the standard data model can be found in the following layout:
config/
oracle.iam.rm.temporal/
standard.xml
standard_permissions.xml
The standard.xml file contains configuration for all objects necessary for the Oracle Role Manager application to function properly.
Attributes in the Oracle Role Manager model are first defined as domains. A domain is an abstract logical data type that when associated with an object type as part of the attribute definitions of an entity, it is then considered an attribute.
Adding attributes in Oracle Role Manager means the domain must be defined before it can be added to an attribute definition. In other words, the domain definition must already exist, either in a configuration that your configuration depends on (such as standard), or earlier in the XML file in which it is being defined as an attribute.
Refer to the "Object Type Definition" and "Model Definition" sections of Appendix A for the schema definition defining which data types and constraints are available for use in attribute definitions.
Example 2-1 Creating an Attribute
This example adds a new attribute to the person structural type with a pattern restriction for specified characters. (Refer to Section 2.5 for more information about structural object types. (Refer to API documentation of the java.util.regex.Pattern class for information about controlling allowed characters in attribute values.)
This change is purely additive, so it can be deployed at any time after the standard model has been deployed.
In a new XML file, the new domain is first defined. For example:
<domain-definitions>
<domain-definition name="favoriteColor">
<t:string>
<t:length id="length" max-length="32">
<t:violation-message>The favorite color can be no longer than 32 characters</t:violation-message>
</t:length>
</t:string>
</domain-definition>
</domain-definitions>
Later in the same file, the person structural type is extended to have the new domain as an attribute along with a special pattern to restrict specified characters. For example:
<type-definitions>
<extension-type-definition extending-type-id="person">
<attribute-definitions>
<attribute domain="favoriteColor">
<title>Favorite Color</title>
<t:pattern id="pattern">
<t:violation-message>The favorite color cannot contain the following characters: # ^ + ! @ = </t:violation-message>
<t:pattern>[^#\^\+\!@\=]+</t:pattern>
</t:pattern>
</attribute>
</attribute-definitions>
</extension-type-definition>
</type-definitions>
The model addition is then deployed as described in Section 2.6, "Extending the Standard Configuration."
Example 2-2 Modifying an Attribute
This example changes the employeeNumber attribute so that it is required for all person objects in the system. In addition, this example adds constraints so it is both required and unique (no duplicates may be created).
Important Note: Because this changes a domain definition that is already in standard model, it cannot be additive and requires that it the modified standard model is deployed on a schema where no standard model has been deployed previously.
In the copy of the standard.xml file, in the section that extends the person object type, <extension-type-definition extending-type-id="person">, the employeeNumber attribute is edited as follows (the modifications are shown in bold type):
<attribute domain="employeeNumber">
<title>Employee Number</title>
<t:string-ext>
<t:non-null-constraint id="non-null">
<t:violation-message>The employee number must be specified.</t:violation-message>
</t:non-null-constraint>
<t:unique-constraint id="unique" case-sensitive="false" type="varying-temporal">
<t:violation-message>The employee number must be unique.</t:violation-message>
</t:unique-constraint>
<t:whitespace id="whitespace">
<t:violation-message>The employee number cannot have leading or trailing spaces.</t:violation-message>
</t:whitespace>
</t:string-ext>
</attribute>
The model addition is then deployed as described in Section 2.7, "Modifying the Standard Configuration."
Relationships in Oracle Role Manager are defined by reference attributes in the object definition. Reference attributes are many-to-one relationships and refer to another object type rather than a primitive type.
Each reference attribute has an ID, the foreign object of the relationship and the IDs and user-friendly titles representing incoming and outgoing relationship paths.
For example, the person object definition contains this reference attribute for the relationship between person and costCenter as shown here:
<reference-attribute id="costCenterOrg_id" foreign-type="abstractOrg"
parent-action="restrict"
outgoing-relationship-path="parent_cost_center_organization"
incoming-relationship-path="child_cost_center_people">
<title>Cost Center Organization</title>
<outgoing-relationship-path-title>Parent Cost Center Organization</outgoing-relationship-path-title>
<incoming-relationship-path-title>Child Cost Center People</incoming-relationship-path-title>
</reference-attribute>
The following table describes the elements of this reference attribute. Refer to the Appendix A, "Object Type Definition" for the schema definition defining these elements.
Table 2-1 Reference Attribute Components
| Attribute | Description |
|---|---|
|
id |
This is the ID of the reference attribute that backs this relationship path. The convention is that the ID be the object type followed by |
|
foreign-type |
The foreign type is the type of object this relationship points to. It can be the same object as the one used as the ID, or it can be its parent object. In the case of the relationship shown previously, the ID is |
|
parent-action |
This optional attribute is used for governing the sphere of control around relationships. The available values are:
Note: If no parent action attribute is set, the default parent action is |
|
outgoing-relationship-path |
The outgoing relationship path represents the path from the object type where the reference attribute is being defined to the object type used as the ID. |
|
incoming-relationship-path |
The incoming relationship path represents the path from the object type used as the ID to the object type where the reference attribute is defined. |
Example 2-3 Creating a Relationship
This example adds a new reference attribute for the one-to-many, person to person relationship between a Review Manager and the people managed by that manager. This change is purely additive, therefore it can be deployed at any time after the standard model has been deployed.
In a new XML file, the person structural type is extended to have the new relationship. For example:
<type-definitions>
<extension-type-definition extending-type-id="person">
<attribute-definitions>
<reference-attribute id="reviewManager_id" foreign-type="person"
outgoing-relationship-path="reviewer_manager_person"
incoming-relationship-path="reviewees_managed_people">
<title>Review Manager</title>
<outgoing-relationship-path-title>
Review Manager
</outgoing-relationship-path-title>
<incoming-relationship-path-title>
Review-Managed People
</incoming-relationship-path-title>
</reference-attribute>
</attribute-definitions>
</extension-type-definition>
</type-definitions>
The model addition is then deployed as described in Section 2.6, "Extending the Standard Configuration."
Structural type objects in the Oracle Role Manager model represent first-class business objects, such as organizations, people, and roles. They have no identifying foreign keys and store attributes and permissions.
Structural type objects can extend other structural type objects, for example like organization does from abstractOrg, or not, depending on the needs of the model.
When adding structural type objects, you can use existing domains in attribute definitions as well as any new domains that you need. Make sure that the domains are defined in the domain definitions before you associate them with the new object type.
Example 2-4 Creating a Structural Type
This example adds a new object type to represent a physical resource and its attributes. It also creates relationships (such the person responsible for the resource and the building that contains the resource) and permissions (manage and audit).
This change is purely additive, so it can be deployed at any time after the standard model has been deployed.
In a new XML file, all the new domains to associate with the new object are first defined. For example:
<domain-definitions>
<domain-definition name="isInWorkingOrder">
<t:boolean/>
</domain-definition>
<domain-definition name="isReservable">
<t:boolean/>
</domain-definition>
</domain-definitions>
Later in the same file, the physicalResource structural type is defined and the previously defined attributes and relationships are associated. For example:
<type-definitions>
<structural-type-definition id="physicalResource">
<title>Physical Resource</title>
<attribute-definitions>
<attribute domain="displayName">
<title>Physical Resource</title>
<t:string-ext>
<t:non-null-constraint id="non-null">
<t:violation-message>The resource name is required.</t:violation-message>
</t:non-null-constraint>
</t:string-ext>
</attribute>
<attribute domain="description">
<title>Description</title>
</attribute>
<attribute domain="isInWorkingOrder">
<title>In Working Order</title>
<t:boolean-ext>
<t:default-value>true</t:default-value>
</t:boolean-ext>
</attribute>
<reference-attribute id="resourceOwner_id" foreign-type="person"
outgoing-relationship-path="resourceOwner"
incoming-relationship-path="ownedResources">
<title>Resource Owner</title>
<outgoing-relationship-path-title>Resource Owner</outgoing-relationship-path-title>
<incoming-relationship-path-title>Owned Resources</incoming-relationship-path-title>
</reference-attribute>
<reference-attribute id="building_id" foreign-type="abstractOrg"
outgoing-relationship-path="parent_building"
incoming-relationship-path="child_resources">
<title>Building</title>
<outgoing-relationship-path-title>Parent Resource Building</outgoing-relationship-path-title>
<incoming-relationship-path-title>Child Building Resources</incoming-relationship-path-title>
</reference-attribute>
</attribute-definitions>
<permissions>
<permission id="audit"/>
<permission id="manage"/>
</permissions>
<access-policy read-audit-details-permission="audit"/>
</structural-type-definition>
</type-definitions>
The model addition is then deployed as described in Section 2.6.
To extend the standard model, you will need to create a new XML file containing your customizations and create a new .car file containing that XML file in the expected directory layout. This file will depend on the standard model also being deployed.
To extend the standard model configuration:
On the Oracle Role Manager host, create a directory for your customization. For example, C:\ORM_HOME\model_custom.
In the new directory, create a subdirectory named config.
In the config directory, create a subdirectory named oracle.iam.rm.temporal.
In the temporal directory, create an XML file that contains the following expected elements at the beginning:
<?xml version="1.0" encoding="UTF-8"?>
<temporal xmlns="http://xmlns.oracle.com/iam/rm/temporal/config/1_0"
xmlns:t="http://xmlns.oracle.com/iam/rm/type/def/1_0"
id="datamodel_custom" version="1.0.0">
<dependencies>
<dependency id="standard" version="3.0.0"/>
</dependencies>
where datamodel_custom is the name of the XML file without the file extension and 1.0.0 is the version to assign to this customization.
Add the configuration you want in the body of the XML, after the dependencies element, in the following order:
New domain definitions
New permission definitions
New or extensions to object type definitions
Make sure the content in this file ends with:
</temporal>
Using a utility like WinZip or jar, repackage everything in the within the directory created in step 1, and create a archive file appended with the .car file extension, for example, datamodel_custom.car.
Open the .car file and ensure that it contains the XML file with the path config/oracle.iam.rm.temporal.
Note:
If it instead isdatamodel_custom/config/oracle.iam.rm.temporal, then your changes will not be deployed to the database.Deploy your model additions by include this file in the collection of .car files following the steps in Section 2.8, "Deploying Data Model Customizations."
To modify the standard model, you will need to edit and repackage the standard configuration before deploying your customizations to the database.
Note:
Care should be taken when modifying object types in the standard model. If you are using the Oracle Role Manager application, changes you make to existing object types in this file could result in errors or unexpected behavior in the application.To modify the standard model configuration:
From the temporary location where standard.car was extracted (refer to Section 2.2), navigate to config/oracle.iam.rm.temporal.
Add or edit the defintions in the standard.xml file as needed.
Note:
If you are deploying a model that has been deployed previously, you must increment the version number.Using a utility like WinZip or jar, repackage everything in the temporary directory and create a new file appended with the .car file extension, for example, datamodel_custom.car.
Include this file in the collection of .car files as part of the deploy command described in Section 2.8.
This procedures assumes that Oracle Role Manager has been successfully installed and the Oracle Role Manager database instance is running.
To deploy data model customizations:
On the Oracle Role Manager installation host, navigate to ORM_HOME/config.
Make sure the db.properties file in ORM_HOME/config contains the correct information for your database environment. If it does not, modify it so it contains the following two lines:
db.driverClass=oracle.jdbc.driver.OracleDriver db.connection_string=jdbc:oracle:thin:@//$HOST$:$PORT$/$SERVICE$
where $HOST$ is the database host name, $PORT$ is the database listener port, and $SERVICE$ is the database instance on which the Oracle Role Manager users/schemas were created.
Stop the Oracle Role Manager application server if it is running.
In a command window, navigate to ORM_HOME/bin.
Run the following command to deploy the configuration
deploy "collection_of_cars" orm-owner ormapp-user admin-user
where:
collection_of_cars contains the relative paths and file names of the .car files to deploy. This collection must be within quotes with delimiters appropriate to the platform (a semicolon (;) for Windows, otherwise a colon (:). For example, if you have customized the standard model and a separate customization that extends the standard model, the .car collection might be:
"../model_custom/datamodel_custom.car;../model_custom/standard_custom.car;"
orm-owner is the user name of the Oracle Role Manager database owner user/schema
ormapp-user is the user name of the Oracle Role Manager application user/schema
admin-user is the user name of the Oracle Role Manager System Administrator.
At the prompts, type the passwords of the database owner, application user, and administrator.
After you have deployed your data model customizations, you can verify the data model changes using a database utility such as Oracl SQL Developer or DB Visualizer.
|
 Copyright © 2008, Oracle. All rights reserved. Legal Notices |
|