Sun Identity Manager 8.1 Business Administrator's Guide

Transaction Management

A transaction encapsulates a single provisioning operation, for example creating a new user or assigning new resources. To ensure that these transactions complete when resources are unavailable, they are written to the Transaction Persistent Store.

The following topics in this section contain procedures for managing service provider transactions:

Setting Default Transaction Execution Options

These options control how transactions are executed, including synchronous/asynchronous processing and when they are persisted to the Transaction Persistent Store. They can be overridden in the IDMXUser view or through the form used to process it. For more information, see Sun Identity Manager Service Provider 8.1 Deployment.

ProcedureTo Configure Service Provider Transactions

  1. Click Service Provider -> Edit Transaction Configuration.

    The Service Provider Transaction Configuration page appears.

    Figure 17–5 shows the Default Transaction Execution options area.

    Figure 17–5 Transaction Configuration

    Figure showing the Service Provider Transaction Configuration
page

  2. Select the appropriate Guaranteed Consistency Level options to specify the level of transaction consistency for user updates.

    These options include:

    • None. No guaranteed ordering of resource updates for a user.

    • Local. Resource updates for a user being processed by the same server are guaranteed to be ordered.

    • Complete. All resource updates for a user are guaranteed to be in order, across all servers. This option requires all transactions to be persisted before attempting the transaction or before asynchronous processing.

  3. Enable the Default Transaction Execution options as needed.

    These options include:

    • Wait for First Attempt. Dictates how control returns to the caller when an IDMXUser view object is checked in. If the option is enabled, the check-in operation is blocked until the provisioning transaction has completed a single attempt. If asynchronous processing is disabled, then the transaction either succeeds or fails when control is returned. If asynchronous processing is enabled, then the transaction continues to be retried in the background. If the option is disabled, the check-in operation returns control to the caller before attempting the provisioning transaction. Consider enabling this option.

    • Enable Asynchronous Processing. This option controls whether processing of provisioning transactions continues after the check-in call returns.

      Enabling asynchronous processing allows the system to retry transactions. It also improves throughput by allowing the worker threads configured in Set Advanced Transaction Processing Settings to run asynchronously. If you select this option, configure the retry intervals and attempts for the resources being provisioned to or updated using the synchronization input form.

      When you select Enable Asynchronous Processing, enter a Retry Timeout value. This is an upper bound expressed in milliseconds of how long the server retries a failed provisioning transaction. This setting complements the retry settings on the individual resources, including the Service Provider user LDAP directory. For example, if this limit is reached before the resource retry limits are reached, the transaction is aborted. If the value is negative, then the number of retries is only limited by the settings of the individual resources.

    • Persist Transactions Before Attempting. If enabled, provisioning transactions are written to the Transaction Persistent Store before they are attempted. Enabling this option might incur unnecessary overhead because most provisioning transactions succeed on the first attempt. Consider disabling this option unless the Wait for First Attempt option is disabled. This option is not available if Complete consistency level is selected.

    • Persist Transactions Before Asynchronous Processing(default selection). If enabled, provisioning transactions are written to the Transaction Persistent Store before they are processed asynchronously. If the Wait for First Attempt option is enabled, then transactions that need to be retried are persisted before control is returned to the caller. If the Wait for First Attempt option is disabled, then transactions are always persisted before they are attempted. It is recommended to enable this option. This option is not available if Complete consistency level is selected.

    • Persist Transactions on Each Update. If enabled, provisioning transactions are persisted after each retry attempt. This can aid in isolating problems because the Transaction Persistent Store, which is searchable from the Search Transaction page, is always up-to-date.

Setting Transaction Persistent Store

The options on the Service Provider Transaction Configuration page apply to the Transaction Persistent Store. The type of store can be configured as well as additional queryable attributes to expose in the store, as shown in the following figure.

Figure 17–6 Configuring Service Provider Transaction Persistent Store

Figure illustrating how to configure the Service Provider Transaction
Persistent Store

ProcedureTo Set Options on the Service Provider Transaction Configuration Page

  1. Select the desired Transaction Persistent Store Type from the list.

    If the Database option is selected, then the RDBMS configured on the main Service Provider configuration page is used for persisting provisioning transactions. This guarantees transactions that must be retried are not lost when a server is restarted. Selecting this option requires configuring the RDBMS on the main Service Provider configuration page. If the Simulated memory-based option is selected, then transactions that require retry are only stored in memory and are lost when the server restarts. Enable the Database option for production environments.


    Note –

    Memory-based transaction persistent store is not suitable for use in clustered environments.

    When Transaction Persistent Store Type is changed, you must restart all running Identity Manager instances for the change to take effect.


  2. If desired, enter Customized queryable user attributes.

    Select additional attributes of the IDMXUser object to expose in transaction summaries. These attributes are queryable from the search transaction page and appear in search results.

    These attributes include:

    • User path expression. Enter a path expression into the IDMXUser object.

    • Display name. Choose a display name corresponding to the path expression. This display name is shown on the transaction search page.

Set Advanced Transaction Processing Settings

These advanced options control the inner-workings of the transaction manager. Do not change the provided defaults unless performance analysis indicates they are not optimal. All entries are required.

Figure 17–5 illustrates the Advanced Transaction Processing Settings area on the Edit Transaction Configuration page.

Figure 17–7 Advanced Transaction Processing Settings

Figure showing the Advanced Transaction Processing Settings
area on the Edit Transaction Configuration page

ProcedureTo Specify Advanced Transaction Processing Settings

  1. Enter the desired number of Worker Threads (default 100).

    This is the number of threads used to process transactions. This value limits the number of transactions that are processed concurrently. These threads are statically allocated at startup.


    Note –

    When the Worker Threads setting is changed, you must restart all running Identity Manager instances for the change to take effect.


  2. Enter the desired Lease Duration (ms) (default 600000).

    This controls how long a server locks a transaction that it is retrying. The lease is renewed as needed. However, if the server does not shutdown cleanly, then another server is not able to lock the transaction until the original server’s lease expires. The value should be at least one minute. Setting the value smaller can impact the load on the Transaction Persistent Store.

  3. Enter the Lease Renewal (ms) time (default 300000).

    This controls when the lease of a locked transaction is renewed. It is renewed when there are this many milliseconds remaining on the lease.

  4. Enter the time to Retain Completed Transactions in Store (ms) (default 360000).

    How many milliseconds to wait before removing completed transactions from the Transaction Persistent Store. Unless transactions are configured to be immediately persisted, the Transaction Persistent Store does not contain all completed transactions.

  5. Enter the Ready Queue Low Water Mark (default 400).

    When the transaction scheduler’s queue of ready-to-run transactions falls below this limit, it refills the queue with any available ready-to-run transactions up to the high water limit.

  6. Enter the Ready Queue High Water Mark (default 800).

    When the transaction scheduler’s queue of ready-to-run transactions falls below the low water mark, it refills the queue with any available ready-to-run transactions up to this limit.

  7. Enter the Pending Queue Low Water Mark (default 2000).

    The transaction scheduler’s pending queue holds failed transactions that are pending a retry. If the size of the queue exceeds the high water mark, then all transactions beyond the low water mark, are flushed to the Transaction Persistent Store.

  8. Enter the Pending Queue High Water Mark (default 2000).

    The transaction scheduler’s pending queue holds failed transactions that are pending a retry. If the size of the queue exceeds the high water mark, then all transactions beyond the low water mark, are flushed to the Transaction Persistent Store.

  9. Enter the Scheduler Period (ms) (default 500).

    This is how often the transaction scheduler should run. When it runs, the transaction scheduler moves ready-to-run transactions from the pending queue to the ready queue, and performs other periodic duties such as persisting transactions to the Transaction Persistent Store.

  10. Click Save to accept the settings.

Monitoring Transactions

Service Provider transactions are written to the Transaction Persistent Store. You can search for transactions in the Transaction Persistent Store to view the transaction status.


Note –

Using the Edit Transaction Configuration page (see Transaction Management), the administrator can control when transactions are persisted. For instance, they can be persisted immediately, even before they are attempted for the first time.


The Transactions Search page allows you to specify search conditions that enable you to filter the transactions to view based on specific criteria related to the transaction event, such as user, type, status, transaction ID, current state and success or failure of the transaction. This includes transactions that are still being retried, as well as transactions that have already completed. Transactions that have not completed can be cancelled preventing any further attempts.

ProcedureTo Search Transactions

  1. In the Administrator interface, click Server Tasks -> Service Provider Transactions.

    The Service Provider Transaction Search page opens, allowing you to specify search conditions.


    Note –

    The search returns only transactions that match all of the conditions selected below. This is similar to the Accounts -> Find Users page.


  2. Configure your search.

    Choose one or more of the following options:

    • User Name. Allows you to search for transactions that apply only to users with the accountId that you enter.


      Note –

      If you have configured any Customized queryable user attributes on the Service Provider Transaction Configuration page, then they appear here. For example, you could choose to search based on Last Name or Full Name if these were configured as customized queryable user attributes.


    • Type. Allows you to search for transactions of the selected type or types.

    • State. Allows you to search for transactions in the following selected state or states:

      • Unattempted transactions have not yet been attempted.

      • Pending retry transactions have been attempted one or more times, have had one or more errors, and are scheduled to be retried up to the retry limits configured for the individual resources.

      • Success transactions have completed successfully.

      • Failure transactions have completed with one or more failures.

    • Attempts. Allows you to search for transactions based on how many times they have been attempted. Failed transactions are retried up to the retry limits configured for the individual resources

    • Submitted. Allows you to search for transactions based on when they were initially submitted in increments of hours, minutes, or days.

    • Completed. Allows you to search for transactions based on when they were completed in increments of hours, minutes, or days.

    • Cancelled Status. Allows you to search for transactions based on whether or not they have already been cancelled.

    • Transaction ID. Allows you to search for transactions based on their unique id. Use this option to find a transaction based on the id value you enter, which appears in all audit log records.

    • Running On. Allows you to search for transactions based on the Service Provider server where they are running. The server’s identifier is based on its machine name unless it has been overridden in the Waveset.properties file.

    • Limit the search to results to first number of entries selected from the list. Only results up to the specified limit are returned. No indication is made if additional results are available.

    Figure 17–8 Search Transactions

    Figure showing the Service Provider Transaction Search
page

  3. Click Search.

    The search results are displayed.

  4. You can click Download All Matched Transactions at the bottom of the results page to save the results to an XML formatted file.


    Note –

    To cancel transactions returned in the search results, select the transaction in the results table and click Cancel Selected. You cannot cancel transactions that have completed or have already been cancelled.