IBM Atlas Policy Distribution Administrators Guide: IER Connector. for IBM Atlas Suite v6

Transcription

1 IBM Atlas Policy Distribution Administrators Guide: IER Connector for IBM Atlas Suite v6

2 IBM Atlas Policy Distribution: IER Connector This edition applies to version 6.0 of IBM Atlas Suite (product numbers 5725-D75, 5725-D76, 5725-D77) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation 2004, US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Contents 1 Introduction IBM Atlas Policy Distribution Connector for IBM Enterprise Records Requirements Workflow Overview Create a Login Module WebSphere JBoss Check the Atlas Configuration Create and Configure a Data Source Create a Data Source Add the IER Connector Associate the Data Source with a Local Schedule Create the Schedules Associate the IER Data Source with a Local Schedule Create and Load an Initial Load File Create the File Load the File Set the Tasks to Completed Modify and Propagate the Schedule Modify the Retention Policy Propagate the Change The Triggering Metadata Field... 26

4 1 Introduction The IBM Atlas Policy Distribution (PD) feature is a semi-automated system that communicates record retention policies from Atlas to an external data repository. There are two parts to this system: A framework that resides on the Atlas application and a Policy Distribution Connector, a stand-alone application that resides on or connects to the data repository: On the Atlas side, IT staff configures a Data Source object that represents the external data repository, and identifies, to that Data Source, the PD Connector that communicates with the data respository. Records Management Office (RMO) users can then associate the Data Source with a Local Schedule (the embodiment of a retention policy). When the RMO user changes an interesting attribute of the Schedule, the steward for the Data Source is asked to propagate the change to the Connector (by simply pushing a button). When the PD Connector is notified of the change to the Schedule, it translates the modification into terms that the external repository understands (by calling the repository s native API). The repository can then apply the changes as it sees fit: By dispositioning records, moving them to storage that s more accessible, enforcing stricter security, and so on. 1.1 IBM Atlas Policy Distribution Connector for IBM Enterprise Records This document tells you how to install, configure, and test the IBM Atlas Policy Distribution Connector for IBM Enterprise Records (the IER Connector). The IER Connector communicates with an IBM Enterprise Records system that manages data in a FileNet repository. I M P O R T A N T In IBM Atlas Suite V (and earlier), the IER Connector isn t literally a Connector the IER Policy Distribution functionality is built into the Atlas application. There is no separate Connector application that needs to be installed. This document describes the built-in IER PD functionality, and uses the term IER Connector as a shorthand for IER PD functionality that s built into Atlas. 1.2 Requirements The IBM Enterprise Records and FileNet servers must be accessible to Atlas through an HTTP connection. In order to configure the IER Connector, you must know the URL of the IER web service, and be able to identify an account that can log into the service as an administrator. You must also be able to identify the FileNet File Plan that you re interested in.

5 IBM Atlas Policy Distribution: IER Connector Introduction 1.3 Workflow Overview The workflow for configuring and testing the IER PD functionality follows this outline: 1 Create a login module in the application server that hosts IER. Atlas will use this module to access the IER system. 2 In Atlas, create a Data Source object that will represent the IER system. 3 Also in Atlas, configure the relevant Components and Timer Tasks. 4 As an RMO user, associate the Data Source with a Local Schedule through the Local Schedule s Record to Repository Matrix page. 5

6 2 Create a Login Module As part of the IER PD functionality, Atlas must be able to log into the IER/FileNet system. It does this through a login module that s added to the application server. This chapter provides instructions for adding a login module to a WebSphere and JBoss server. 2.1 WebSphere If you re using WebSphere as the Atlas application server, do this: 1 Log into the WebSphere Integrated Solutions Console (the administration console). 2 In the task tree, open the Security node and click Secure administration, applications, and infrastructure: 3 In the authentication area, open the Java Authentication and Authorization Service node and click Application logins:

7 IBM Atlas Policy Distribution: IER Connector Create a Login Module 4 The login list appears; click New at the top of the list: 5 In the Configuration area, enter FileNetP8WSI in the Alias field and click Apply: 6 After the screen refreshes, click Save in the Messages area, and then click the JAAS login modules link in Additional Properties. 7 The login module list appears; click New at the top of the list: 7

8 Create a Login Module IBM Atlas Policy Distribution: IER Connector 8 In the Configuration area, enter com.filenet.api.util.wsiloginmodule in the Module class name field, make sure Authentication strategy is set to Required, and click Apply: 9 After the screen refreshes, click Save in the Messages area, and then click the Custom properties link in Additional Properties. 10 The custom properties list appears. If you don t see an entry named delegate, click New and supply these values: Name: delegate Value: com.filenet.api.util.wsiloginmodule When you ve finished, click Apply: 11 After the screen refreshes, click Save in the Messages area. 12 Restart the application server. 8

9 IBM Atlas Policy Distribution: IER Connector Create a Login Module 2.2 JBoss If you re using JBoss as your application server, open the login-config.xml file that s located in the Atlas domain directory and add the following application-policy element to the end of the file (but within the closing </policy> element): <application-policy name="filenetp8wsi"> <authentication> <login-module code="com.filenet.api.util.wsiloginmodule" flag="required"/> </authentication> </application-policy> When you ve finished, save and close the file, and then restart the application server. 9

10 3 Check the Atlas Configuration Before you can tell Atlas to use your IER Connector, you have to make sure that the system is configured to display the Policy Distribution UI and support the PD mechanisms. Log into Atlas as a System Administrator, go to the Admin tab and do this: Make sure the ENABLE_POLICY_DISTRIBUTION Parameter in the PA_CONFIGURATION Component is set to Yes. Make sure the IER Policy Distribution Automated Propagation Task Timer Task is enabled. If you d like, you can adjust the frequency of the task, as explained in the IBM Atlas Suite Administrators Guide: Timer Tasks book. If you re testing a Policy Distribution deployment, such as outlined in the document, you may also want to do this: Go to the AWF_CONFIGURATION Component and set the SCHEDULE_AWF_ENABLED and TEMPLATE_AWF_ENABLED Parameters to False. This will make approving Master and Local Schedules easier. Go to the Admin > Data Source Maintenance module and relax the mandatory field requirements for savng approving a Data Source. See the IBM Atlas Suite Administrators Guide: System Configuration book for details on how to use the module. I M P O R T A N T You should only change the AWF_CONFIGURATION Component and Data Source Maintenance module in a test environment, and, even then, only if you re sure that your settings won t affect other testers.

11 4 Create and Configure a Data Source In this chapter, you ll create a Data Source, in Atlas, that will represent the IER system. To follow the instructions in this chapter, you must have create and modify permission for Data Sources. You must also be designated as a Data Source Approver. N O T E The Data Source Approver role is assigned through the DS_APPROVER Component. 4.1 Create a Data Source 1 Log into Atlas with an account that has the Data Source Approver role.

12 Create and Configure a Data Source IBM Atlas Policy Distribution: IER Connector 2 On the Data Source Details page, provide information about the Data Source (the fields that are required depend on how your system is configured). Make sure the Manage Policy Distribution checkbox is checked: 3 Scroll down to the Organization section and associate the Data Source with an Organization: As we ll see later, a Local Schedule can only propagate policy changes to Data Sources that are associated with the Local Schedule s Admin Organization. 4 Scroll a bit more to the Staff section and add a Steward: Only the Data Source s Steward is allowed to perform policy propagation tasks. In a real deployment you may want to add more than one Steward. 5 Save and then Approve your new Data Source. (The approval action will pop up an approval-comments dialog; you don t have to leave comments, just click Ok.) 12

13 IBM Atlas Policy Distribution: IER Connector Create and Configure a Data Source 4.2 Add the IER Connector In this section, you ll add the IER Connector to the Data Source that you just created. 1 Back in the Data Source Details page, click the Policy Distribution tab: 2 You ll see this warning message: This is expected. Dismiss the message by clicking Ok. 3 Click the Setup tab and supply the information that identifies your IER and FileNet systems: Set the Vendor to P8 IER. Identify the FileNet file plan, within a file plan object store (FPOS), that you want Atlas to access by setting the Connector Info field in this form: FilePlanObjectStoreName/FilePlanName N O T E Check the two Enable checkboxes. This will enable the other fields. Currently, the Enable automated policy propagation checkbox doesn t mean that the propagation of retention policies, from Atlas to the Connector, will be fully automated. However, you do have to check the checkbox in order to enable the other fields. In the three newly-enabled fields, identify the URL of the IER web service, and the username and password of an IER administrator account. Click Save. 13

14 Create and Configure a Data Source IBM Atlas Policy Distribution: IER Connector 4 You should see this message; click Ok: 5 Go back to Map > Data Sources and click Catalog Management. You ll see the Change Request for the Data Source you just created: 14

15 IBM Atlas Policy Distribution: IER Connector Create and Configure a Data Source 6 Click on the name of the Data Source. After the page refreshes, click Approve (and, again, click Ok in the comments dialog): Your Data Source is now ready to be used for Policy Distribution. 15

16 5 Associate the Data Source with a Local Schedule At this point, the system is fully configured to support policy distribution. The rest of this document tests the configuration. In this chapter, you ll act as an RMO employee; you will: Create a Master Schedule. Create a Local Schedule that s based on the Master Schedule. Associate your IER Data Source with the Local Schedule. To follow the instructions in this chapter, you must have create, update, and execute permission for Master and Local Schedules (execute permission is necessary for approval). N O T E The System Administrator account, which we ve been using in the examples so far, has the proper permissions for these instructions. 5.1 Create the Schedules Before you create the Schedules, open the AWF_CONFIGURATION Component and make sure that both SCHEDULE_AWF_ENABLED and TEMPLATE_AWF_ENABLED are set to False:

17 IBM Atlas Policy Distribution: IER Connector Associate the Data Source with a Local Schedule Create a Master Schedule 1 Go to the Schedules > Classification Library module, click the radio button next to the CORPORATE Record Class (the top node in the Schedule hierarchy), and click New Master Schedule: 2 Fill in the required fields in the top part of the page: 3 Scroll down to the Official Retention Schedule section and set the policies to whatever you like. You must set all three policies (Not Applicable is a valid setting): 4 Click Save and then, when the page refreshes, click Approve. 17

18 Associate the Data Source with a Local Schedule IBM Atlas Policy Distribution: IER Connector Create a Local Schedule 1 Go to Schedules > Local Schedules and click New. 2 Click Copy from Master Schedule, click the Classification Library tab in the Resource Chooser on the right, click the radio button next to the Master Schedule you just created, and then click Select: The Local Schedule will be populated with the data from the Master Schedule. 3 Click Admin Organization, check the Corporate checkbox, and then click Select: We re using Corporate because that s the Organization that we associated with the IER Data Source. In an actual deployment, you would probably use some other Organization, but the correspondence holds: The Local Schedule must use an Admin Organization that s associated with the IER Data Source. 18

19 IBM Atlas Policy Distribution: IER Connector Associate the Data Source with a Local Schedule 4 Back over on the left, select an Office of Records and a Records Coordinator: It doesn t matter what you select, here. These settings have no technical significance, but they re required for approval. 5 Click Save. 5.2 Associate the IER Data Source with a Local Schedule 1 Click the Record to Repository Matrix tab and then click Edit: 2 You should see your Data Source listed on the left (don t click it, yet): If you don t see your Data Source, check the following: Is the Data Source associated with the same Organization as the Admin Organization for the Schedule? Is the Data Source configured for IER Policy Distribution (in the Data Source > Policy Distribution tab)? Did you approve the Data Source after you configured PD? (This step is easy to forget after you configure the PD Connector, you re not prompted to approve.) 19

20 Associate the Data Source with a Local Schedule IBM Atlas Policy Distribution: IER Connector 3 Assuming that your Data Source is apparent, do the following: Set the Record Type(s) dropdown menu to 1. Click Add. Supply a name in the Record Types column. Click the upper-left dog ear in the Official cell for your new record type; the cell will turn green: 4 Now drag your Data Source into the green cell: 5 When you re finished, click Save & Close: 6 Return to the Schedule s Details page and click Approve. The Local Schedule is now configured so it can be used in the Policy Distribution system. 20

21 6 Create and Load an Initial Load File After you ve associated a Local Schedule (or set of Local Schedules) with an IER-aware Data Source, you must create an Initial Load file and load it into FileNet. The Initial Load file is a manifest that, among other things, lists and describes the Schedules that you want to propagate to the IER system. You only have to create and load this file once: When you associate additional Local Schedules with the Data Source, these new Schedules description will be propagated through the normal push the Propagate button method. 6.1 Create the File 1 Log into Atlas as the IER Data Source Steward and navigate to the IER Data Source. 2 Go to the Policy Distribution tab and select the Local Schedule you just created (you ll also entries for the Master Schedule and Record Class objects that the Local Schedule inherits from). The panel on the right will give info about the Schedule, and will complain that the Triggering Metadata Field hasn t been specified. Click the icon:

22 Create and Load an Initial Load File IBM Atlas Policy Distribution: IER Connector 3 Supply the name of an IER record field (or folder field) that you know exists: The field you choose represents the the event, as it s known to IER, that, when modified, initiates disposition of records that adhere to the Schedule s retention policy. We ll talk more about the exact meaning in the final chapter. 4 Click Initial Load. A dialog will ask you if you want to Also reset Policy Distribution Tasks. Leave the checkbox unchecked (we ll explain why later in this chapter) and click Proceed: 5 The system will create a file named InitialLoadDoc.xml. Save the file on your local machine. The next steps are performed on the IER/FileNet machine. 6.2 Load the File In this section, you ll load the Initial Load file into IER. To understand these instructions, you need to be familiar with FileNet s File Plan Import Export tool, and with the IER interface and concepts. The steps, below, do not attempt to provide thorough explanations of the FileNet and IER tools and functions, but are provided as examples. 1 Copy the Initial Load file onto the machine that hosts FileNet. 2 Open a command window, cd to the FileNet directory that contains the File Plan Import/Export tool. By default, it lives here: C:\Program Files (x86)\ibm\filenet\rm\fileplanimportexporttool 3 Configure the Tool (if it isn t already configured) by running the FilePlanTool script in configure mode: $ FilePlanImportExportTool -mode configure 22

23 IBM Atlas Policy Distribution: IER Connector Create and Load an Initial Load File A configuration panel will open. Supply the required information. Refer to the FileNet documentation if you re unsure how to configure the tool. 4 Run the script in import mode to import the Initial Load file. For example: $ FilePlanTool -mode import -f C:\tmp\initialLoadDoc.xml reimportoption Replace The f switch gives the location of the Initial Load file. 5 Launch IER, expand the Category Tree, and make sure the Schedule hierarchy (CORPORATE > IER Test Schedule > IER Test Schedule, in our example) has been imported. 6.3 Set the Tasks to Completed Return to the Policy Distribution Management page in Atlas. Notice that the three Policy Distribution tasks are still marked as Execute. Now that the Initial Load file has been successfully imported into IER, you should mark the tasks as Completed (you have to do this one-by-one, starting with the Add Record Class task): If you had checked the Also reset Policy Distribution Tasks when you created the Initial Load file, the system would have automatically (and immediately) set the tasks states to Completed. This is convenient if you re loading a number of Schedules and you re reasonably sure that the load will be successful. 23

24 7 Modify and Propagate the Schedule In this chapter, you ll modify the IER Local Schedule (as an RMO), and then propagate the change (as IT staff). 7.1 Modify the Retention Policy 1 Return to the Details tab for the IER Test Schedule Local Schedule and click Edit Schedule Details. 2 Scroll down to the Retention Schedules, change the Retention Type to Event + Fixed Time and set the Disposition value: 3 Provide a Reason for Change and then click Save & Close. 4 When the screen refreshes, click Approve. 7.2 Propagate the Change 1 Go to the My Alerts tray on your My Atlas page; notice that you have a Policy Distribution task:

25 IBM Atlas Policy Distribution: IER Connector Modify and Propagate the Schedule 2 Go to the My Tasks > Policy Distribution tab and notice that the task is listed there, as well: 3 Click the Data Source Name link and you ll be taken to the Policy Distribution tab for the Data Source. Select the Change Local Schedule task, and then click Propagate: 4 The propagation task will proceed in the background. Click the Logs tab to watch its progress. The task s status will initially be set to Propagation In Progress. After a couple minutes, you should see a pair of entries that announce that the propagation has completed, and that it was successful. 25

26 8 The Triggering Metadata Field The Triggering Metadata Field that you specified when you created the Initial Load document maps a Disposition Event in Atlas to a record field in IER. The Policy Distribution Connector monitors this field; when the field changes (or, more likely, is set), the event is assumed to have occurred, and the disposition clock starts ticking. For example, let s say you want to (or are allowed to) disposition product collateral ten years after the product has reached the end of life. In Atlas, as we ve seen, you would configure the retention policy thus: Now you need to tell IER how to interpret the End of Product Life event. You did this by specifying the EndOfLIfe field when you created the Triggering Rule: What this means is that when the EndOfLife field is set (or modified) in an IER record that adheres to the retention policy that s defined by this Local Schedule, that record will be dispositioned in ten years. Some details: Specifying a Triggering Rule does not create the field in IER. The field must already exist. In Atlas, you can select one of three effective disposition configurations: Event, Event + Fixed Time, or Fixed Time. All three of these configurations are, in reality, interpreted as Event + Fixed Time. If you select Event, the Fixed Time part of the equation is 0. If you select Fixed Time, the Event is a change to the triggering field. Thus, the Event, as displayed in Atlas, doesn t really matter.