11 Using the Task Archival Utility

This chapter describes how to use the Task Archival utility. It contains the following topics:

• Understanding the Task Archival Utility

• Preparing Oracle Database for the Task Archival Utility

• Preparing Microsoft SQL Server for the Task Archival Utility

• Running the Task Archival Utility

• Reviewing the Output Files Generated by the Task Archival Utility

11.1 Understanding the Task Archival Utility

In Oracle Identity Manager, a task refers to one or more activities that comprise a process, which handles the provisioning of a resource. For example, a process for requesting access to a resource may include multiple approval and provisioning tasks. Oracle Identity Manager stores task data in the following tables, which are called active task tables:

• OSI

• OSH

• SCH

By default, Oracle Identity Manager does not remove completed tasks from the active task tables. As the size of the active task tables increases, you might experience a reduction in performance, especially when managing open tasks and pending approvals. After a task executes successfully, you can use the Task Archival utility to archive the task data and remove it from the active task tables. Archiving task data with the Task Archival utility improves performance and ensures that the data is safely stored.

The Task Archival utility stores archived task data in the following archive task tables, which have the same structure as the active task tables:

• ARCH_OSI

• ARCH_OSH

• ARCH_SCH

You can use the Task Archival utility to archive the following types of tasks:

• Provisioning tasks for resource instances that have been revoked for disabled or deleted users

• Provisioning tasks for resource instances that have been revoked

• Approval tasks with a request status of Request Complete, Request Cancelled, or Object Approval Complete

When you archive tasks with the Task Archival utility, you can specify the type of archive operation, the user status, the task execution date, and the number of records on which to drop the indexes before archiving. The archive operation represents the type of task data to archive and the user status determines whether to archive data for users who have been deleted, disabled, or both. The task execution date represents the date on which a task is executed and must be in the format YYYYMMDD.

All executed tasks, up to the task execution date you specify, will be archived. To reduce the time that the archiving process takes, the utility drops the indexes on all active task tables when the number of records to be archived is greater than 200000. The indexes are re-created after the archived data is deleted from the active task tables. You can change the value 200000 to your preferred value. You can change the value in the following lines of code in the OIM_TasksArch.bat file or in the OIM_TasksArch.sh file:

In the .bat file, set INDXRESP=200000

In the .sh file, indxopt=200000

The files that constitute the Oracle Database version of the Task Archival utility are located in the following directory:

OIM_HOME/xellerate/Database/Oracle/Utilities/TaskArchival

The files that constitute the Microsoft SQL Server version of the Task Archival utility are located in the following directory:

OIM_HOME/xellerate/Database/SQLServer/Utilities/TaskArchival

Note:

Data that has been archived from the active task tables to the archive task tables will no longer be available through Oracle Identity Manager. To access this data, you must query the archive task tables in your Oracle Identity Manager database.

11.2 Preparing Oracle Database for the Task Archival Utility

Before you can use the Task Archival utility with Oracle Database, you must perform the following steps:

1. Start SQL*Plus and connect to Oracle Database as a SYS user.

2. Create a separate tablespace for the archival task tables by entering the following command. Replace DATA_DIR with the directory in which you want to store the data file and adjust the size and other parameters as necessary for your environment.

   CREATE TABLESPACE TasksArch
       DATAFILE 'DATA_DIR\tasksarch_01.dbf' SIZE 1000M REUSE
       EXTENT MANAGEMENT LOCAL SEGMENT SPACE MANAGEMENT AUTO;
   

   Note:

   Oracle recommends that you allocate a large UNDO tablespace when archiving large amounts of data. In addition, turn on parallel execution by configuring the parallel_max_servers and parallel_min_servers initialization parameters. Parallel execution helps improve the performance of the archival process.

3. Connect to Oracle Database as the Oracle Identity Manager database user.

4. If you plan to run the Task Archival utility on an Oracle Identity Manager release that is earlier than 9.1.0, then execute the following command. This command adds the ORC_TASKS_ARCHIVED column to the ORC table. The Task Archival utility updates this column to value of 1, which indicates that the tasks for that particular process instance have been archived.

   ALTER TABLE ORC ADD(ORC_TASKS_ARCHIVED VARCHAR2(1))
   

5. Enter the following command to run the cr_taskarchival_ddl_table.sql script, which creates a table named OIM_TASK_ARCH_DDL. This table is used by the Task Archival utility.

   @ path/cr_taskarchival_ddl_table.sql
   

6. Enter the following command to run the Create_TasksArch_Tables.sql script, which creates the archive task tables:

   @ path/Create_TasksArch_Tables.sql
   

7. Enter the following command to run the OIM_SP_TASKS_ARCHIVAL.sql script, which creates a stored procedure that the Task Archival utility uses to archive and delete task data:

   @ path/OIM_SP_TASKS_ARCHIVAL.sql
   

8. If your Oracle Database instance is running in ARCHIVELOG mode, you must switch to NOARCHIVELOG mode before running the Task Archival utility. See Oracle Database Administrator's Guide for information about changing the database archiving mode.

11.3 Preparing Microsoft SQL Server for the Task Archival Utility

Before you can use the Task Archival utility with Microsoft SQL Server, you must perform the following steps:

1. If you have added any custom indexes to the OSI, SCH, or OSH tables, then you must also add them to the path/Create_TasksArch_Indexes.sql file.

2. Start SQL Query Analyzer and connect to SQL Server as a user that is a member of sysadmin, or who has a dbcreator server role or db_owner database role.

3. Enter the following commands. Replace DATA_DIR with the directory in which you want to store the data file and adjust the SIZE, MAXSIZE, and FILEGROWTH parameters as necessary for your environment. These commands create the OIM_ARCH_TASKS file group, which the Task Archival utility uses to store data from archive task tables.

   USE master
   GO
   ALTER DATABASE oim_database_name
   ADD FILEGROUP OIM_ARCH_TASKS
   GO
   ALTER DATABASE oim_database_name 
   ADD FILE 
    (NAME = OIM_ARCH_TASKS,
     FILENAME = 'DATA_DIR\OIM_ARCH_TASKS.NDF',
     SIZE = 1000MB,
     MAXSIZE = 5000MB,
     FILEGROWTH = 25MB)
   TO FILEGROUP OIM_ARCH_TASKS
   GO
   

4. Disconnect from SQL Server and reconnect again as the Oracle Identity Manager database user.

5. If you plan to run the Task Archival utility on an Oracle Identity Manager release that is earlier than 9.1.0, then execute the following command. This command adds the ORC_TASKS_ARCHIVED column to the ORC table. The Task Archival utility updates this column to value of 1, which indicates that the tasks for that particular process instance have been archived.

   ALTER TABLE ORC ADD ORC_TASKS_ARCHIVED VARCHAR(1)
   

6. Load and execute the path/Create_TasksArch_Tables.sql script, which creates the archive task tables.

7. Load and execute the path/OIM_SP_TASKS_ARCHIVAL.sql script, which creates a stored procedure that the Task Archival utility uses to archive and delete task data.

11.4 Running the Task Archival Utility

Perform the following steps to run the Task Archival utility:

1. Ensure that the Oracle Identity Manager database is available and that no reconciliation processes are running. Also, ensure that the Oracle Identity Manager database is not open to transactions for other sessions.

   Note:

   Oracle recommends that you run the Task Archival utility during off-peak hours.

2. Back up the OSI, SCH, and OSH tables.

3. Stop Oracle Identity Manager by following the instructions in the Oracle Identity Manager installation guide for your application server.

4. On Microsoft Windows platforms, you must specify the short date format as dddd M/d/yyyy. In addition, you must specify the time format as H:mm:ss. To customize the date and time formats, select the Regional and Language Options command in the Control Panel.

   Note:

   When you change the date and time format, all applications running on the Microsoft Windows platform will be affected.

5. On Linux and UNIX platforms, run the path/OIM_TasksArch.sh file. On Microsoft Windows platforms, run the path\OIM_TasksArch.bat file.

6. For Oracle Database installations, enter values for the following parameters when prompted:

   • Oracle home directory

   • Oracle Identity Manager database name or TNS string if the Oracle Identity Manager database is running on a remote computer

   • Oracle Identity Manager database user name and password

   For Microsoft SQL Server installations, enter values for the following parameters when prompted:

   • Server name where the SQL Server database is running

   • Oracle Identity Manager database name

   • Oracle Identity Manager database user name and password

7. When prompted, select one of the following options:

   • Archive all provisioning tasks on resource instances that have been revoked for disabled or deleted users.

   • Archive all provisioning tasks on resource instances that have been revoked.

   • Archive all approval tasks in which the request status is Request Complete, Request Cancelled, or Object Approval Complete.

   • Exit.

8. If you chose to archive all provisioning tasks for resource instances that have been revoked for disabled or deleted users, select one of the following options:

   • Users at Deleted status

   • Users at Disabled status

   • Users at Deleted and Disabled status

   • Go back to Main Menu

9. Enter a task execution date in the format YYYYMMDD when prompted. All executed tasks, up to the task execution date you specify, will be archived. To archive all tasks that were executed on or before the current date, press Enter without entering a date.

10. Enter a value of y or Y when prompted to archive the tasks. Otherwise, enter a value of n or N to exit the utility.

    Note:

    You must enter the value of Y or N when prompted. If you press Enter without selecting a value, then the utility again counts the number of tasks to be archived and prompts you without beginning the archive.

11. On Microsoft Windows platforms, reset the short date format to the date format for your region or locale after the Task Archival utility finishes running. Use the Regional and Language Options command in the Control Panel to reset the date format.

    Note:

    Because the data from active task tables is removed, you must analyze the active task tables and their indexes for updated statistics. Perform this step only if you are using Oracle Database as the database for Oracle Identity Manager.

11.5 Reviewing the Output Files Generated by the Task Archival Utility

Table 11-1 describes the output files that are generated by the Task Archival utility.

Table 11-1 Output Files Generated by the Task Archival Utility

File	Description
Err_DB_Conn_timestamp.log	Generated when the utility is unable to connect to the database with the specified credentials
Err_Arch_Tasks_timestamp.log	Generated when the archival or deletion processes fail
Arch_TaskData_timestamp.log	Generated when the archival or deletion processes succeed

Note:

These error log files are deleted when you run the utility again.