Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Adaptive Access Manager
Release 11g (11.1.1)

Part Number E14568-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

20 Creating and Managing Entities

A transaction is a process such as bill pay, wire transfer, address change, and so on. The core elements of an Oracle Adaptive Access Manager transaction are entities and transaction data. Entities can be defined and associated as an instance of a transaction.

This chapter provides information on creating, editing, activating and deactivating, and importing and exporting entities.

20.1 Introduction and Concepts

This section introduces you to the concept of entities.

20.1.1 Entities

An Entity is a user-defined data structure, which comprises of a set of attributes. The entity can be re-used across different transactions. An example of an entity is an address. When associating the entity with a transaction you can create a shipping address and billing address from the address entity.

Figure 20-1 Address Entity

This diagram illustrates the Address entity

20.1.2 Data Elements

Data elements are used to describe the attributes that make up an entity. For example, the credit card entity has attributes such as address line 1, address line 2, city, zip, and state. Data elements, such as description, length, type, and so on, are used to describe each attribute.

20.1.3 Display Element

Display elements are the elements you want to present and the order in which you want to present the value of an entity in a user interface. For example, if you want to display an address, you would want to show address line 1 as the first item, address line 2 as the second item, city as the third item, state as the fourth item, and zipcode as the fifth item.

20.1.4 ID Scheme

An ID scheme consists of the data elements that can uniquely identify an entity, in other words, you are defining the unique combination that identifies the entity. For example, the credit card entity has many attributes, but the way to uniquely identify a credit card is by using the 16-digit credit card number. In that case, the ID scheme is just the credit card number.

Another example, the address entity has address line 1, address line 2, city, state, and zipcode as attributes. Address line 1, address line 2, and zipcode, without the state and city attributes, can still be used to identify the address uniquely.

20.1.5 Internal ID

The internal identifier used to identify a data element in the entity. It is created based on the display name. For example, if Address Line 1 is the display name, spaces between words are replaced by decimals to create an internal ID.

Examples of internal IDs are Address.Line.1, Address.Line.2, or Zip.Code.

The IDs are automatically created for you.

20.1.6 External ID

The client supplies the Ext ID value. Oracle Adaptive Access Manager can either store this value for the client or use it to identify the entity. For example, a client may send merchant, product, and customer entities. These entities already have IDs with the client.

20.2 Navigating to the Entities Search Page

To navigate to the Entities Search page, double-click Entities in the Navigation tree.

Alternatively, you can:

The Entities Search page is the starting place for managing entities. From the Entities Search page, you can:

An example of an Entities Search page is shown in Figure 20-2.

Figure 20-2 Entities Search page

The Entities search page is shown.

20.3 Searching for Entities

To search for entities:

  1. Navigate to the Entities Search page, as described in Section 20.2, "Navigating to the Entities Search Page."

  2. Specify criteria in the Search Filter to locate the entity.

    The search filter criteria are described in Table 20-1.

    Table 20-1 Search Filter Criteria

    Field Description

    Name

    The name of the entity.

    Description keyword

    The description keyword

    Status

    The status of the entity.


  3. Click Search.

The Search Results table displays a summary of entities that match the criteria specified in the Name, Description Keyword, and Status fields.

There is a link on the entity name. To view the entity details, click the link.

20.4 Creating an Entity

Follow the steps in this section to create a new entity. You will have to provide the required information for all tabs of the Entities Details page before you can activate the entity.

Note:

After creating an entity, you must activate it if you want to use it in a transaction. Only active entities can be used in a transaction. By default an entity is disabled when it is created. For information on activating an entity, refer to Section 20.9, "Activating Entities."

20.4.1 Initial Steps

To create an entity, follow these steps.

  1. Navigate to the Entities Search page, as described in Section 20.2, "Navigating to the Entities Search Page."

  2. In the Entities Search page, click the New Entity button.

    Alternative methods to open create pages are listed in Section 3.9, "Search, Create, and Import."

    An example of a New Entity page is shown in Figure 20-3.

    Figure 20-3 New Entity Page

    The New Entity page is shown.
  3. In the New Entity page, enter a unique entity name.

  4. Enter a description about the data element. For example, you can enter "Credit card number of customer" or "Account number of customer."

  5. Click Apply.

    A confirmation dialog appears with a message that the entity was created successfully.

  6. Click OK to dismiss the dialog.

    The Entity Details page appears for the entity that you have just created.

    The page contains four tabs:

    • Summary - General Details

    • Data - Data Elements (Used for adding and editing data elements of entity)

    • ID Scheme - Data Elements (Used for adding and editing data elements of an entity)

    • Display - Display Elements (Used for adding and editing display elements of the entity based on the Identification Scheme)

    The tab titles for Data, ID Scheme, and Display will show the number of data elements present, in parenthesis, when you have added your elements.

20.4.2 Adding and Editing Data Elements

The Data tab is used for adding and editing data elements of an entity.

In the Data tab, specify the data elements that are part of that entity.

For example, for an entity like Address, the elements are Address Line 1, Address Line 2, City, State and Zip code. Metadata elements, such as a label, description, data type, and so on, describe these elements of the entity.

Define the data elements for each element by following these instructions:

  1. Enter a label.

    For example, Address Line 1, Address Line 2, City, or Zip code.

  2. Enter a description about the data element.

    Data elements are the attributes of an entity.

    For example, the address of the customer logging in.

  3. Specify whether the element is required.

    Some data elements are not populated all the time because the entity can function without this data. Those elements are marked as "not required." For example "Address Line 2" in an address is not required since many addresses do not have "Address Line 2."

  4. Specify whether the element should be encrypted.

    If Is Encrypted? is set to True, data is encrypted so that it can be stored securely in the database; thereby protecting sensitive data.

    Encrypted fields have the following constraints:

    • These fields should not be used in rules. If they are used, you cannot specify regular values for comparing against these fields; the values will have to be encrypted values.

    • These fields cannot be used in the search criteria while querying for transactions through the query screen.

      Numeric fields cannot be encrypted.

    Encrypted fields can be displayed in OAAM Admin.

  5. Specify the data element Data Type.

    For example, String.

  6. If you want to add another element, click the Add button on the toolbar and repeat Steps 1 through 7.

  7. Click Save.

You can use the Delete button to delete the data elements within the entity.

Note:

The Row and Column values are automatically assigned based on the data type and should not be changed unless you want to rearrange values in the database.

20.4.3 Selecting Elements for the ID Scheme

In the ID Scheme tab, select the elements that you want to use to uniquely identify an entity.

For example, the credit card entity has many attributes, but the way to uniquely identify a credit card is by using the 16-digit credit card number. In that case, the ID scheme is just the credit card number.

Another example, the address entity has Address Line 1, Address Line 2, City, State, and Zip code as attributes. The Address Line 1, Address Line 2, and Zip code attributes can be used to identify the address uniquely. The State and City attributes are not necessary.

Address Line 1 alone would not uniquely identify an address. For example, 150 Main Street can exist in more than one location.

An example of a ID Scheme tab is shown in Figure 20-4.

Figure 20-4 ID Scheme tab

The entity ID Scheme page is shown
  1. Select the Data Identification Scheme.

    Identification Scheme determines how an entity is uniquely identified using the elements that are part of the entity. The elements that are selected should be stored as plain text (key) or encrypted (digest).

    • By Key: This scheme creates a unique identifier by simply concatenating the selected elements of the entity.

    • By Digest: This scheme creates a unique identifier by hashing the values of the selected elements of the entity. The resultant key is usually cryptic. Use this scheme when the data values are large or if they need to be secured.

  2. Click the Add button on the toolbar to add a data element.

  3. In the Add Data Elements screen, select the data elements to add to the ID Scheme and click Add.

    You can select one or several data elements to add to the identification scheme.

    For example, you only need the 16-digit credit card number to identify the credit card.

    After the data elements are added, they are not available in the list for further selection.

  4. Select the order of the elements

    The order determines how the data is concatenated while forming the data that identifies the entity. Order is not required and is automatically pre-filled if you do not fill in that information.

You can use the Delete button to delete the data elements within the entity.

20.4.4 Specifying Data for the Display Scheme

In the Display tab, define the display scheme. The display scheme specifies the data elements to present and their order when you display the value of the entity in reports:

  • The data elements form the entity data that can be displayed.

  • The order determines how the data is concatenated while forming the data to be displayed for the entity

An example of a Display tab is shown in Figure 20-5.

Figure 20-5 Display tab

The entity Display page is shown.

The Data elements that you have selected to present are shown in the Transaction Details page.

To select the data elements, follow these steps.

  1. Click the Add button to add a data element.

  2. In the Add Data Elements screen, select the data elements to add for displaying and click Add.

    For example, for an address, you can choose to present Address Line 1, City, State, and Zip code.

  3. Select the order of the elements

    The order determines what is shown first, second, third, and so on when the data is displayed for the entity. Order is not required and is automatically pre-filled if you do not fill in that information.

    For example, if you want to display an address, you would want to show address line 1 as the first item, address line 2 as the second item, city as the third item, state as the fourth item, and Zip code as the fifth item.

You can use the Delete button to delete the display elements.

20.4.5 Activating the Entity

After creating an entity, you must activate it if you want to use it in a transaction. Only active entities can be used in a transaction. By default an entity is disabled when it is created. For information on activating an entity, refer to Section 20.9, "Activating Entities."

20.5 Viewing Details of a Specific Entity

To view the details of a specific entity:

  1. Navigate to the Entities Search page, as described in Section 20.2, "Navigating to the Entities Search Page."

  2. From the Entities Search page, search for the entity you want.

    The filters are described in Table 20-1.

  3. In the Results table, click the entity name.

    An example of an Entity Details page is shown in Figure 20-6.

    Figure 20-6 Entity Details page

    The Entity Details page is shown.

20.6 Editing the Entity

To edit the details of a specific entity:

Note:

Be cautious when editing entities. If you edit an entity and it is in several transactions, then the edits are applied to all instances of the entity in the different transactions.
  1. If you are not on the Entity Details page of the entity you want to edit, follow the instructions in Section 20.5, "Viewing Details of a Specific Entity."

  2. From the Summary tab, you can modify the name and description of the entity; and activate or deactivate the entity.

  3. From Data and ID Schemes tabs, you can modify the data elements of the entity.

    If you delete a data element from the scheme, it is added to the Add list and available the next time you select Add Data Elements.

  4. From the Display tab, you can edit the way the entity is displayed.

  5. Click Apply.

20.7 Exporting Entities

To export entities:

  1. Navigate to the Entities Search page, as described in Section 20.2, "Navigating to the Entities Search Page."

  2. In the Entities Search page, enter the search criteria you want and click Search. Refer to Section 20.3, "Searching for Entities."

  3. Select the row for each entity you want to export.

  4. Click the Export button or select Export Selected from the Actions menu.

  5. In the Export Entities screen, click Export.

  6. In the Save screen, click OK.

20.8 Importing Entities

To import entities:

  1. Navigate to the Entities Search page, as described in Section 20.2, "Navigating to the Entities Search Page."

  2. In the Entities Search page, click Import.

  3. In the Entities Import screen, click Browse and locate the entity file you want to import.

  4. Click OK.

20.9 Activating Entities

To activate entities:

  1. Navigate to the Entities Search page, as described in Section 20.2, "Navigating to the Entities Search Page."

  2. In the Entities Search page, enter the search criteria you want and click Search. Refer to Section 20.3, "Searching for Entities."

  3. Select the row for each entity you want to activate.

  4. Press the Activate button.

    When you press Activate, the entity is validated for errors (if data elements are present). If there are any errors, they must be fixed before the entity is activated.

    Only active entities can be used in a transaction. Make sure to activate an entity definition if you want to use it in a transaction.

20.10 Deactivating Entities

To deactivate entities:

  1. Navigate to the Entities Search page, as described in Section 20.2, "Navigating to the Entities Search Page."

  2. In the Entities Search page, enter the search criteria you want and click Search. Refer to Section 20.3, "Searching for Entities."

  3. Select the row for each entity you want to deactivate.

  4. Press the Deactivate button.

20.11 Deleting Entities

To delete entities:

  1. Navigate to the Entities Search page, as described in Section 20.2, "Navigating to the Entities Search Page."

  2. In the Entities Search page, enter the search criteria you want and click Search. Refer to Section 20.3, "Searching for Entities."

  3. Select the row for each entity you want to delete and select the Delete button from the toolbar.

    If the entities selected for deletion are not used or linked to a transaction, a warning message is shown asking for confirmation.

    If an entity is used, you will not be allowed to delete it.

  4. Click Delete to delete the entities.

  5. In the confirmation dialog, click Yes.

When multiple entities are selected for deletion and if there are transactions that contain the instances of some of the entities selected, a warning message is provided, stating "The following instances are linked to transactions and cannot be deleted. Do you want to delete the other entities?" If you click Delete, the unlinked entities are deleted.

If you deactivate an entity, it will not be available for you to use in transactions.

20.12 Re-ordering the Rows in the ID Scheme and Display tabs

After adding all the elements, you can reorder the columns by dragging and dropping the rows for the ID scheme and Display tabs. Both in ID Scheme and Display tabs, order is important.

The order of the rows in the ID scheme tab determines how information is stored in database and used uniquely identify.

The order of the rows in the Display tab determines the order in which information is presented.

For example, in the display, you may want "City, State, Zip code" for addresses in the UK and USA.

20.13 Best Practices

This section outlines some best practices for entity creation.