IBM Atlas Suite Administrators Guide: Importing Data through CSV Files. for IBM Atlas Suite v6

Transcription

1 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files for IBM Atlas Suite v6

2 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files 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 CSV Import Configuration CSV Templates Rules for Creating and Populating CSV Files Class Object Documentation Format Column Documentation Format Organizations, Roles, and Persons Organizations Roles and Permissions Persons Data Sources Data Sources Related Data Sources Legal Matter Security and Request Scope Matter Security Groups Add People to Scope Citations Overview GeoTypes GeoNodes Jurisdictions Jurisdiction Mapping Agencies Citations Schedules Overview Retention Schedule Events Schedule Templates (Master Schedules and Record Classes) Local Schedules Local Schedule/Data Source Mapping... 63

4 1 Introduction Many of the IBM Atlas Suite features depend on a replication of your company s business hierarchy lists of employees, organization hierarchy, data repository catalogs, and so on. In most companies, this data is represented in an existing database. There are three ways to get this data into Atlas: You can enter it manually through the GUI. This is fine for small, one-off pieces of data, but for importing employee data and org charts, it s not workable. You can export your native data to a CSV file and then import the file through the Admin > Import CSV File page. This is better and it s probably how you ll import (and update) much of your data but it isn t automated: You have to manually upload the CSV files into Atlas when new data is created or when existing data needs to be updated. You can use Atlas Extensions, an application that lets you automate the process of importing (and updating) Person, Organization, and Matter information from an external source. You don t have to use an intermediate storage medium and you don t have to push any buttons: Changes that you make to your native database are automatically propagated to Atlas. This book describes how to configure and use the CSV import feature, and provides a specification of the CSV file format. 1.1 CSV Import Configuration The CSV import feature is configured through these Components and Parameters: DOCUMENT_LIBRARY > TEMP_DIRECTORY. This is the full pathname to the directory on the application server that the CSV importer uses to store the CSV files that you upload. The directory must already exist the system won t create it for you and it must allow read/write/execute permissions for the owner. Note that this directory is used by all Atlas processes that import and export files it isn t exclusively for the use of the CSV importer. CSV_IMPORT > LOG_FILE_NAME. As the CSV importer parses a CSV file, it annotates its success or failure by appending entries to the log file identified by this Parameter. Again, the value must be a full pathname to a directory on the application server (with read/write/execute permissions), but the directory needn t already exist; the system will create it for you. The leaf name of the logfile must be data-import.log. For example: Windows: C:\ATLAS\logs\data-import.log UNIX: //ATLAS/logs/data-import.log

5 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Introduction 1.2 CSV Templates The system supplies a set of CSV template files, one for each type (or class) of object. Each template file is laid out thus: The first column of the first row names the class of objects that the file will create/update: Organizations, Persons, Events, and so on. A single CSV file can only create one class of objects you can t mix Organizations and Data Sources in the same file (for example). The second row lists the class attributes. You mustn t change the order of the columns in this row, nor may you rename them. The rest of the file is empty you create/update objects, one object per row, by supplying values for the attributes, saving the file, and importing it into Atlas. For example, the Role Permissions template looks like this: After you ve finished filling in the data, you can import the file into the Atlas application Downloading and Importing the CSV Templates To download the CSV templates files, do this: 1 Log into the Atlas application and go to Admin > Import CSV Data. 2 Click the Click here to download the CSV templates link. 3 The templates are delivered in a zipfile, CSVTemplates.zip. Save the file on your computer. 4 Extract the templates that you need from the zipfile. To import a CSV file into Atlas, do this: 1 Save the file using any filename you wish Atlas doesn t care about the filename, it gets all the information it needs from the file s contents. 2 Go to Admin > Import CSV Data and either type in the full pathname of your file or Browse to it, and then click Import: 5

6 Introduction IBM Atlas Suite Administrators Guide: Importing Data through CSV Files 3 After the file has been imported, Atlas will a present a link to the CSV Import log file: Clicking the link will open the file in a text editor. If the file is too big to open in the default editor, right-click the link, save the file, and open it in a different editor. 1.3 Rules for Creating and Populating CSV Files Observe the following rules when creating and populating your CSV files: The name of the CSV file is ignored. The template files that you can download from the Atlas application are named for the class of object that they create (as specified in the first row of the file), but you can rename the files as you please. However, the file must have a.csv extension otherwise the importer will reject it. A single CSV file contains data for only one class of object. The first column of the first row in the file identifies the object class name. The class names are given in the individual CSV specifications that make up the bulk of this book. A CSV file must contain every column for its object class, and in the order specified in the templates. The column names are case-sensitive. A CSV file may not contain extra columns. The data in a cell must not be surrounded by extra whitespace. The data in a cell must not contain newline characters. If you want the data to break the line (this is useful in description fields, for example), insert the character sequence ^n where you want the line to break. The sequence must include leading and trailing whitespace; for example: "This is line one. ^n This is line two." The columns that take lists of values expect precise formatting of these lists. For example, an Organization hierarchy must be formed as Org1: Org2: Org3, with no space before the delimiter ( : ) and only one space after. The specifications will tell you how you must format these lists Commas and Double-quotes N O T E If you re creating your CSV files directly in Excel or some other CSV-aware spreadsheet program, this section doesn t apply to you. The program should handle commas and double-quotes properly. Since the comma is used as a delimiter in the CSV file, you have to protect values that contain commas by placing them (the values) in double-quotes. For example, let s say you want to create a Description field in the Citations CSV contains this text: This can be used at the state, county, or city level. To pass in this value, you have to put double-quotes around the entire value: 6

7 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Introduction "This can be used at the state, county, or city level." Now let s say the value also naturally contains double-quotes: This can be used at the "state," "county," and "city" level. Once again you have to wrap the entire value in double-quotes, and then you have place a double-quote before each of the naturally-occurring double-quotes: "This can be used at the ""state,"" ""county,"" and ""city"" level." 1.4 Class Object Documentation Format Each CSV class object (Persons, Organizations, Data Sources, etc) is documented in its own major section. At the beginning of each section is a header that looks like this: CREATE CLASS NAME: DataSources UPDATE CLASS NAME: DataSources-update TEMPLATE: DataSources.csv PREREQUISITES: Persons, Organizations EMPTY VALUE: SET_TO_EMPTY The header components are: CREATE CLASS NAME is the class name that must appear in the first cell of the first row for CSV files that create new objects. UPDATE CLASS NAME is the class name for files that update existing objects. Not all CSV have versions that update their objects. TEMPLATE is the name of the CSV template file that s provided by Atlas. PREREQUISITES lists the other CSV objects that the class uses as values. EMPTY VALUE tells you how to erase an existing value during an update. There are two methods: NULL means that if a column is given no value (if it s empty), the value of the corresponding attribute will be erased. SET_TO_EMPTY means that an empty column leaves the attribute s current value alone. If, in this case, you want to remove the attribute s value, you must use the SET_TO_EMPTY token as the column s value. Following the header is a general description of the objects that the CSV creates, followed by specifications for the CSV columns (as described in the next section). After the column descriptions are two final sections: ObjectName Error Messages. Most CSV files produce error messages (in the import logfile) that are reasonably selfdocumenting. This section lists exceptions or other notable messages. Not all CSV class specifications include an Error Messages section. ObjectName in the Atlas UI. This section provides a screenshot of the Atlas UI page (or pages) that presents the data that the CSV file imports, and provides a correspondence between CSV columns and the data as it s displayed in the UI. Not all CSV classes are presented in the Atlas UI, so not all of the specifications will include this section. 7

8 Introduction IBM Atlas Suite Administrators Guide: Importing Data through CSV Files 1.5 Column Documentation Format The column specifications in this document are presented in this format: Name STRING[250] Required, Unique, Update Key The name of the Data Source as it s known to the system. For creation, the name must be caseinsensitive unique across all Data Sources; for updating, the value must match the name (case-sensitive) of an existing Data Source The first line gives the name of the column, the type of data it takes, and its requirements. The following text describes the attribute that the column represents and makes further comments about the column s value. The data types are: STRING[N]. The column contains user-defined text data that has a maximum length of N. TOKEN. The column takes a value that s already defined in the system. The list of values that the column can take is given in the column description. BOOLEAN. The column contains a Boolean value: Y means true; N (or blank) means false. DATE. The column contains a date in the form mm/dd/yyyy ; for example, 04/21/2001. FLOAT. The value is a number that includes a fractional part ( 4.25, for example). The requirements are: Update Key. This indicates that the column s value is used to find an existing object during an update. Co-update Key. The column is part of a multi-valued update key. Classes that use multi-valued update keys will have two or more Co-update Key designations. Unique. The column s value must be unique across all objects (of the same class), including objects that already exist in the Atlas database (in other words, it isn t enough for the value to be unique just within the CSV file). Required. You must supply a value for the column. The designation may be qualified for specific circumstances (Required for Creation, Required for Update, and so on). Required if Checked. This is used for custom data fields. For most objects, the requirement of a custom field is determined through the Admin > Custom Fields > Object Class page. For Data Sources, the custom field requirements are controlled through the Admin > Data Source Maintenance module. Optional. You don t have to supply a value for the column. 8

9 2 Organizations, Roles, and Persons 2.1 Organizations CREATE CLASS NAME: Organizations UPDATE CLASS NAME: Organizations-update PREREQUISITES: None TEMPLATE: Organizations.csv EMPTY VALUE: SET_TO_EMPTY The Organizations CSV creates or modifies an Organization Organizations Columns OrgPath STRING[2000] Required, Unique, Update Key The pathname of the Organization that you re creating or modifying. If you re creating a new Organization, this column must be formed as a concatenation of the ParentOrgPath value and the Name value, colon-separated. For example, if ParentOrgPath is Corporate: Sales and Name is Midwest, the OrgPath value must be set to: Corporate: Sales: Midwest If you re updating an Organization, the OrgPath is the pathname of the Organization that you want to change. If you supply a new Name or ParentOrgPath value, the Organization will be renamed or moved. I M P O R T A N T The Organization names in the pathname must be separated by a colon and a single whitespace (with no whitespace before the colon), as shown in the example. Identifier STRING[250] Required An additional identifier for the Organization. This is typically a unique value that s read from an external system (although note that the system doesn t reject non-unique Identifier values). In the Atlas UI, this attribute is called Identifier it s not the Organization ID attribute (which is a unique number assigned by the system when the Organization is created). Note that in Atlas Extensions, the source table column that holds this value (called OrgID) is required and is the unique identifier for an Organization. Name STRING[250] Required The name of the Organization. If you re creating a new Organization you must use this value as the final element in the OrgPath value. (See OrgPath for more information.) If you re updating an Organization, this will become the Organization s new name.

10 Organizations, Roles, and Persons IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Description STRING[2000] Optional A human-readable description of the Organization. ParentOrgPath STRING[2000] Required The pathname of this Organization s parent Organization. The parent Organization must already exist. If you re creating a new Organization you must use this value as the beginning of the OrgPath value. (See OrgPath for more information.) If you re updating an Organization, this will become the Organization s new parent. The elements in the pathname are Organization names (as given in the Name column) and are colon-separated; for example: Corporate: HR: Personnel I M P O R T A N T The Organization names must be separated by a colon and a single whitespace (with no whitespace before the colon), as shown in the example. OrgType STRING[50] Optional The Organization s type. You can use this column as a way to organize or otherwise classify your Organizations. There are no rules regarding the value s format you can use any name you want. N O T E The OrgType value is brought out by the rep_organizations_vw Reporting View, but it isn t presented (and can t be created) through the Map > Organizations and Admin > Organizations pages. OrgLocation STRING[2000] Optional The Organization s geographical location. You can use this column as a way to organize or otherwise classify your Organizations. There are no rules regarding the value s format you can use any designation you want. N O T E The OrgLocation value is brought out by the rep_organizations_vw Reporting View, but it isn t presented (and can t be created) through the Map > Organizations and Admin > Organizations modules. OrgCountry STRING Optional The country in which the Organization is located, in the form ISOCode:CountryName ; for example: US:United States The set of valid values is defined by the COUNTRIES Component, where each Parameter s name is the ISOCode portion and its value is the CountryName. I M P O R T A N T The ISOCode and Country Name elements must be separated by a colon and no whitespace, as shown in the example. IsGlobalOfficeOfRecords BOOLEAN Optional If this is Y, the Organization is added to the list of candidate Office of Records for Local Schedules. if it s N (or empty during creation), it isn t added to the list. It s an error to supply any other value. Don t use SET_TO_EMPTY in an update use N, instead. 10

11 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Organizations, Roles, and Persons PAField1 STRING[2000] Required if Checked PAField2 STRING[2000] Required if Checked PAField3 STRING[2000] Required if Checked PAField4 STRING[2000] Required if Checked PAField5 STRING[2000] Required if Checked Custom data. To present these attributes in the Atlas UI, go to Admin > Custom Fields > OrgUnit and check the Visible checkbox. If you check the Required checkbox, a value (here) is required Organizations in the Atlas UI PAGE: Map > Organizations > Select Organization 1 generated by the system 2 ParentOrgPath 3 Name 4 Identifier 5 Description 6 IsGlobalOfficeOfRecords 7 Country When marked as Visible, the custom data fields (PAField1 through PAField5) are displayed between Country and Modified By. 8 generated by the system 9 generated by the system 11

12 Organizations, Roles, and Persons IBM Atlas Suite Administrators Guide: Importing Data through CSV Files 2.2 Roles and Permissions CREATE CLASS NAME: ROLEPERMISSIONS UPDATE CLASS NAME: ROLEPERMISSIONS PREREQUISITES: None TEMPLATE: ROLEPERMISSIONS.csv EMPTY VALUE: NULL The Role and Permissions CSV lets you specify the system object permissions that apply to a Role. There s no update version of the file if the named Role doesn t exist (based on the ROLE_NAME column), it s created; if it does, it s updated. The system objects that are protected by permissions are listed in the Admin > Object Permissions page. The objects include Persons, Organizations, Legal Matters, and so on. For each object, there s a set of operations: Read, Create, Update, Delete, and Execute. Each of these operations has its own permission setting. Thus, for example, you can allow a Role to Read and Create Requests, but not Update, Delete, or Execute them. Exactly what an operation implies for a given object depends on the object. For an explanation of the objects and permissions, see the IBM Atlas Suite Administrators Guide: System Configuration. Each row in the file sets the permissions for a single system object for a Role. Since there are many system objects, the same Role can (and probably will) appear many times in the file Roles and Permissions Columns ROLE_NAME STRING[250] Required, Update Key The name of the Role that you re creating or modifying. If the Role doesn t already exist, it s created. If it does, it s updated. DESCRIPTION STRING[2000] Optional A description of the Role. MY_ATLAS_CONFIGURATION NA NA Currently unused; leave the column empty. SYSTEM_OBJECT STRING Required The name of the system object for which you re setting permissions. A list of system object names are provided in the Name column of the Admin > Object Permissions table. Only those objects that are enabled (as displayed in the Enabled Permissions column) are regarded by the importer. It isn t an error to pass a disabled object, but neither is it effective. I M P O R T A N T The system objects are also presented in the Admin > Roles details page. However, the names used there are actually the objects Description values and can t be used in the Roles and Permissions CSV. 12

13 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Organizations, Roles, and Persons READ BOOLEAN Optional CREATE BOOLEAN Optional UPDATE BOOLEAN Optional DELETE BOOLEAN Optional EXECUTE BOOLEAN Optional These are the system object operations. If you leave the column blank or set the value to N (case-insensitive), permission is demied. Any other value grants permission. READ permission is automatically allowed when you grant permission for any of the other operations. ROLE_VISIBILITY STRING[2000] Optional A list of existing Roles (pipe-separated) that Persons with this Role are allowed to assign to other Persons. For example, this ROLE_NAME: Attorney ROLE_VISIBILITY: LegalAssistant Paralegal means that an Attorney Role can assign other Person to be a LegalAssistant or a Paralegal (assuming that the Attorney Role has been granted UPDATE permission for the Personsystem object) Roles and Permissions in the Atlas UI PAGE: Admin > Roles > Select Role 1 ROLE_NAME 2 DESCRIPTION 3 MY_ATLAS_CONFIGURATION 4 none 5 generated by the system 13

14 Organizations, Roles, and Persons IBM Atlas Suite Administrators Guide: Importing Data through CSV Files 6 generated by the system 7 SYSTEM_OBJECT 8 READ 9 CREATE 10 UPDATE 11 DELETE 12 EXECUTE 13 ROLE_VISIBILITY 14

15 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Organizations, Roles, and Persons 2.3 Persons CREATE CLASS NAME: Persons UPDATE CLASS NAME: Persons-update PREREQUISITES: Organizations, Roles and Permissions TEMPLATE: Persons.csv EMPTY VALUE: SET_TO_EMPTY The Persons CSV creates or modifies Person accounts Persons Columns LoginID STRING[250] Required, Unique, Update Key The Person s Atlas application login string. The value must be case-insensitive unique across all login strings. First Name STRING[250] Required The Person s first name. Last Name STRING[250] Required The Person s last name. Title STRING[300] Optional The Person s job title. STRING[250] Required The Person s address. Note that the CSV importer doesn t validate the form of the address. Password STRING[250] Optional The Person s Atlas application password. If you create a Person without a password (or delete the password during an update), the Person will be asked to create a new password the next time he or she logs into Atlas (assuming that you re using Atlas for authentication). Identifier STRING[250] See below An additional identifier for the Person. This is, typically, a value that uniquely identifies the record that represents the Person in an external database. In the Atlas UI, this attribute is called Person Identifier; in the Atlas Extensions Person Source Table, it s called PersonID. If the PA_DATA_INTEGRITY > UNQ_PERSONIDENTIFIER Component Parameter is set to Yes, the identifier is required and must be unique. If it s No, the identifier is optional and needn t be unique. Atlas Extensions uses this attribute as the Person update key. Thus, if you want to create Person records through the Person CSV and then update these records through Atlas Extensions, you must supply a unique Identifier value, regadless of the UNQ_PERSONIDENTIFIER value. 15

16 Organizations, Roles, and Persons IBM Atlas Suite Administrators Guide: Importing Data through CSV Files MemberOf STRING[4000] Optional A list of Organizations, given by their pathnames, to which the Person will be added as a Member (a Person without a Role in the Organization). The elements within a pathname are Organization names and are colonseparated; multiple paths are pipe-separated. For example, this Corporate: HR: Personnel Corporate: Operations: Purchasing Corporate: Admin adds the Person (as a Member) to: Corporate: HR: Personnel Corporate: Operations: Purchasing Corporate: Admin I M P O R T A N T The Organization names in a pathname must be separated by a colon and a single whitespace (with no whitespace before the colon), as shown in the example. RoleOrgUnitMap STRING[4000] Optional This is similar to MemberOf, but it adds the Person as a User (a Person with a Role in the Organization). Each Role/Organization assignment is given as Role OrgPath where Role is the name of an existing Atlas Role, and OrgPath is an Organization pathname, a colon-separated series of (existing) Organization names. Individual Role/Organization pairs are pipe-separated: Role1 OrgPath1 Role2 OrgPath2 Role3 OrgPath3 RoleN OrgPathN For example, this Manager Corporate: HR: Personnel Attorney Corporate: Operations: Purchasing assigns the Person these Role in these Organizations: Manager in Corporate: HR: Personnel Attorney in Corporate: Operations: Purchasing. I M P O R T A N T The Organization names in a pathname must be separated by a colon and a single whitespace (with no whitespace before the colon), as shown in the example. PAField1 STRING[2000] Required if Checked PAField2 STRING[2000] Required if Checked PAField3 STRING[2000] Required if Checked PAField4 STRING[2000] Required if Checked PAField5 STRING[2000] Required if Checked General custom data. To present these attributes in the Atlas UI, go to Admin > Custom Fields > Persons and check the Visible checkbox. If you check the Required checkbox, a value (here) is required. Status STRING Required The status of the Person s Atlas application account. Valid values (case-sensitive) are: ACTIVE. The Person can log into Atlas, and can be used in the definitions of other objects. 16

17 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Organizations, Roles, and Persons N O T E N O T E DISABLED. The Person can t log into Atlas, and can t be used in the definitions of other objects. Also, the Person is removed from the Organizations that he or she is part of. If you reactive the Person later, you have to explicitly recreate the Organization associations. If you re creating a new Person, the Status value will be automatically set to ACTIVE. The NULL means no change feature doesn t apply to Status. You must supply a Status value during update, even if you don t want to change the status Persons Error Messages The Person error messages that are written to the CSV log file are mostly self-documenting. They consist, primarily, of errors that announce that a required value is missing, that a named entity doesn t exist, or that a value is badly formatted. When an error is found, an initial message that identifies the errant row is printed: ERROR - Person import failed for: [[loginid, First Name, Last Name, etc]]. A message that identifies the bad column is then printed. Note that the following MemberOf and RoleOrgUnitMap errors are non-fatal. The faulty Organization or Role values are ignored, and the Person record is created or updated: Org unit path [Org in MemberOf] does not exist. Role OrgUnit Map must contain an even number of entries. [RoleOrgUnitMap] ERROR - System Role [Role from RoleOrgUnitMap] does not exist. ERROR - Org Unit [Org from RoleOrgUnitMap] does not exist. Error encountered while updating system roles for [LoginID]. See log for details. If any error was found in the file, a final message is printed: :03:57,022 ERROR - CSV Import was Unsuccessful Keep in mind that only those rows that had errors are rejected. Rows without errors will successfully create or modify the targeted Person. There s no Import was successful message. If there were no errors, the importer prints nothing to the logfile. 17

18 Organizations, Roles, and Persons IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Persons in the Atlas UI PAGE: Map > Person > Select Person > LastName, FirstName Details 1 First Name 2 Last Name 3 4 LoginID 5 Title 6 none 7 none 8 PAFieldN 9 PAFieldN 10 Identifier 11 RoleOrgUnitMap (even values) 12 RoleOrgUnitMap (odd values) 13 none 14 none 15 MemberOf 16 none 17 none 18

19 3 Data Sources A Data Source object represents a real-world repository of information. Although the repository is typically a computer or other electronic storage system, it could be anything a filing cabinet or a box in a warehouse, as examples. There are two Data Sources CSVs: Data Sources is the primary CSV. It provides most of the information about a Data Source. Related Data Sources is an optional configuration that lets you create associations between Data Sources. 3.1 Data Sources CREATE CLASS NAME: DataSources UPDATE CLASS NAME: DataSources PREREQUISITES: Persons, Organizations TEMPLATE: DataSources.csv EMPTY VALUE: NULL A Data Source object represents a real-world repository of information. Although the repository is typically a computer or other electronic storage system, it could be anything a filing cabinet or a box in a warehouse, as examples. In addition to the attributes that you define here, you can associate two Data Sources through the Related Data Sources file, as described in the next chapter Defining a Data Source The sections, below, describe some of the things you should keep in mind when defining a new Data Source Identification The Data Sources that you create and modify through the CSV file are uniquely identified by the value in the Identifier column. An additional Name column is provided so you can attach the name of the Data Source as it s known in an external system. However, these two attributes might not provide enough information to identify and categorize all the Data Sources that need to be created. To help with this, the Data Source definition provides additional attributes, notably Category and Type, that can be used to help identify your Data Sources. Category, for example, could be used to group Data Sources that have common access or maintenance characteristics all of your SharePoint servers could be in one category, while your ECM systems are in another Scoping and Organizations If the Data Source is used throughout your company an archive, for example you should consider setting the Is Global column to Y (true). Global Data Sources are added to the Scope of all new Legal Requests. However, if the Data Source is used by specific Organizations within your company, you might not want to set Is Global, but, instead,

20 Data Sources IBM Atlas Suite Administrators Guide: Importing Data through CSV Files identify the Organizations by listing them in the Organizations column. This will help you identify the affected Organizations when scoping a Request or mapping a Local Schedule Stewards and Discovery Delegates The Stewards and Discovery Delegates columns let you list the people (identified by their Person accounts) who are responsible for managing and collecting data from the Data Source. By convention, Stewards are responsible for managing the Data Source as a device while Discovery Delegates are responsible for finding (and possibly collecting) data that resides on the Data Source. When a Data Source is added to the Scope of a Request, all Stewards and Discovery Delegates are added, as well Extended Attributes The Data Source definition provides a number of extended attributes that capture information regarding data retention and collection. Included among these are Accessibility, Fixed Collection Cost, Media Type, Data Structure, and Information Type. The sets of values that these attributes take are typically defined by Components. The default values are listed in the column specifications; you can augment the default values by editing the Component through the Admin > Components module. Internally, the system doesn t use these attributes they re provided purely as a convenient way for you to tag your Data Sources with commonly-needed information Required Columns and Approval When you import a Data Source CSV, the system immediately tries to approve the Data Sources creations and modifications. In order to be approved, the fields that are marked as required in the Fields Required for Approval profile in the Admin > Data Source Maintenance module must be supplied. Regardless of how Fields Required for Approval is configured, you must always supply these fields: Name, Identifier, Category, Status, and Reason for Change. The system doesn t actually check to see if you (the importer) are designated as a Data Source Approver (as defined by the DS_APPROVER Component). It simply assumes that you are Data Sources Columns I M P O R T A N T I M P O R T A N T Unless otherwise noted, all string comparisons are case-sensitive. When updating a Data Source, an empty column erases the attribute s current value. If you re updating a Data Source in order to change the value of a single attribute, you must supply the current values of all its other attributes. Name STRING[250] Required The name of the Data Source as it s known to the system. If the name you supply for a new Data Source isn t unique, the system automatically appends -N where N is a monotonically increasing integer starting with 1. 20

21 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Data Sources Identifier STRING[2000] Required, Update key A unique identifier for the Data Source. If the value matches the identifier for an existing, active Data Source, the row is used to update that Data Source; if it matches an inactive Data Source, the importer throws an error. If the identifier doesn t match an existing Data Source, the row is used to create a new Data Source. Category STRING[2000] Required if Checked (see Required Columns and Approval) The name of an existing Data Source Category. The Category is a tag that you can use to organize your Data Sources for easier searching (for example); it has no other significance for the system. You have to create the Category through the Map > Data Sources > Data Source Categories page before you can use it here. A default Category, Uncategorized, is provided by the system. Manage PD BOOLEAN Required if Checked (see Required Columns and Approval) Whether or not the Data Source supports Policy Distribution: Y if it does; N if it doesn t. Custody STRING Required if Checked (see Required Columns and Approval) The Data Source s custody type. Valid values (case-insensitive) are: Custodial System. The Data Source actually stores data. Controller. The Data Source controls access to a data repository. Start Date DATE Required if Checked (see Required Columns and Approval) End Date DATE Required if Checked (see Required Columns and Approval) The day and time that the Data Source came online and went offline (or will come online/offline). These dates are provided for information only; they have no effect on the Data Source s capabilities. The values are in the form mm/dd/yyyy ; for example, 12/31/2010. Description STRING[2000] Required if Checked (see Required Columns and Approval) A human-readable description of the Data Source. Status STRING Required if Checked (see Required Columns and Approval) The Data Source s state. Valid values (case-insensitive) are: Active. The Data Source is approved and added to the Data Source Catalog. In Progress. The Data Source is added to Data Source Catalog Management as a change request where it waits for approval. Inactive. If the submitter has a Data Source Approver Role, the Data Source is immediately deactivated, otherwise a deactivation request is added to Data Source Catalog Management. Is Global BOOLEAN Required if Checked (see Required Columns and Approval) If Y or y, the Data Source is added to the Scope of all new Requests (assuming that the Data Source is active). If it s any other value, the Data Source must be manually added. 21

22 Data Sources IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Data Source Pafield1 STRING[2000] Required if Checked (see Required Columns and Approval) Data Source Pafield2 STRING[2000] Required if Checked (see Required Columns and Approval) Data Source Pafield3 STRING[2000] Required if Checked (see Required Columns and Approval) Data Source Pafield4 STRING[2000] Required if Checked (see Required Columns and Approval) Data Source Pafield5 STRING[2000] Required if Checked (see Required Columns and Approval) Custom data. To present these attributes in the Atlas UI and add them to the Data Source Maintenance profiles, go to Admin > Custom Fields > DataSource and check the Visible checkbox. Unlike other custom data fields, these fields requirements are set through Admin > Data Source Maintenance; the requirements aren t set though the Custom Fields module. Data Source Comments STRING[2000] Required if Checked (see Required Columns and Approval) Comments about the Data Source. Source System STRING[2000] Required if Checked (see Required Columns and Approval) Source ID STRING[2000] Required if Checked (see Required Columns and Approval) These two columns identify the external system that this Data Source represents. The source system information is brought out through the Reporting Views only; it isn t presented in the Atlas UI. Reason for Change STRING[4000] Required An explanation of why the Data Source is being created or updated. Accesibility STRING Required if Checked (see Required Columns and Approval) I M P O R T A N T The column s name is misspelled. You must use the name shown here don t use Accessibility. The ease with which the Data Source s data can be accessed. The set of valid values is defined by the ACCESSIBILITY Component; the default set is: Easily Accessible Archive Disaster Recovery This is an extended attribute. How you define and interpret a Data Source s Accessibility is up to you. For more information, see Extended Attributes. Fixed Collection Cost FLOAT Required if Checked (see Required Columns and Approval) The overhead cost that s incurred when data is collected from the Data Source. The quanta and currency for the cost value is undefined; for example, 4.25 can mean four dollars and twenty-five cents, or four-thousand-two-hundredand-fifty Euros, or whatever else you want it to mean. Discovery Comments STRING[4000] Required if Checked (see Required Columns and Approval) Human-readable comments about the Data Source s discovery characteristics. 22

23 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Data Sources Discovery Custom1 STRING[4000] Required if Checked (see Required Columns and Approval) Discovery Custom2 STRING[4000] Required if Checked (see Required Columns and Approval) Discovery Custom3 STRING[4000] Required if Checked (see Required Columns and Approval) Discovery Custom4 STRING[4000] Required if Checked (see Required Columns and Approval) Discovery Custom5 STRING[4000] Required if Checked (see Required Columns and Approval) Custom data regarding the Data Source s discovery characteristics. To present these attributes in the Atlas UI, go to Admin > Custom Fields > DataSourceDiscovery and check the Visible checkbox. Media Type STRING Required if Checked (see Required Columns and Approval) The type of media that the Data Source contains or controls. The set of valid values is defined by the MEDIATYPES Component; the default set is: Electronic Paper/Physical Electronic and Paper/Physical This is an extended attribute. How you define and interpret a Data Source s media type is up to you. For more information, see Extended Attributes. Security Level STRING[2000] Required if Checked (see Required Columns and Approval) A list of security settings. The set of valid values is defined by the SECURITYLEVEL Component; the default set is: Confidential Internal Personally Identifiable Information Public Restricted Individual elements in the list are pipe-separated; for example: Confidential Restricted Internal This is an extended attribute. How you define and interpret a Data Source s security level is up to you. For more information, see Extended Attributes. Information Type STRING Required if Checked (see Required Columns and Approval) The type of information that the Data Source contains or controls. The set of valid values is defined by the INFORMATIONTYPE Component; the default set is: Records Records and Transient Transient The information type attribute is provided for information only. How you define and interpret the value is up to you. This is an extended attribute. How you define and interpret a Data Source s information type is up to you. For more information, see Extended Attributes. 23

24 Data Sources IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Data Structure STRING Required if Checked (see Required Columns and Approval) The structure of the data that the Data Source contains or controls. The set of valid values is defined by the DATASTRUCTURE Component; the default set is: Structured UnStructured This is an extended attribute. How you define and interpret a Data Source s data structure is up to you. For more information, see Extended Attributes. DataManagement Comments STRING[4000] Required if Checked (see Required Columns and Approval) Human-readable comments about the Data Source s data. DM Custom1 STRING[4000] Required if Checked (see Required Columns and Approval) DM Custom2 STRING[4000] Required if Checked (see Required Columns and Approval) DM Custom3 STRING[4000] Required if Checked (see Required Columns and Approval) DM Custom4 STRING[4000] Required if Checked (see Required Columns and Approval) DM Custom5 STRING[4000] Required if Checked (see Required Columns and Approval) Custom data regarding the Data Source s data management characteristics. To present these attributes in the Atlas UI, go to Admin > Custom Fields > DataSourceDataManagement and check the Visible checkbox. If you check the Required checkbox, a value (here) is required. Country STRING Required if Checked (see Required Columns and Approval) The country in which the Data Source is located, in the form ISOCode:Country Name ; for example: US:United States The set of valid values is defined by the COUNTRIES Component, where each Parameter s name is the ISOCode portion and its value is the CountryName. I M P O R T A N T The ISOCode and Country Name elements must be separated by a colon and no whitespace, as shown in the example. Managed By STRING Required if Checked (see Required Columns and Approval) Indicates where the Data Source is located or how it s managed. The set of valid values is defined by the MANAGEDBY Component; the default set is: Vendor Internal This is an extended attribute. How you define and interpret a Data Source s the attribute is up to you. For more information, see Extended Attributes. 24

25 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Data Sources Type STRING[2000] Required if Checked (see Required Columns and Approval) The human-readable name of the Data Source s location type. The location type defines the set of attributes that describe the Data Source s location. These attributes correspond to the next 15 columns, from Address through Location pafield5. If you don t supply a Type value, or if the location type doesn t use a particular attribute, the corresponding column is ignored. For example, if you define a location type that doesn t use the Zip attribute, the Zip column in the CSV file will be ignored. To create a location type, go to Map > Data Sources > Data Source Types and click New. You ll see a page that lists the location attributes. The Name is the value you ll supply in this column (Type). To include an attribute in the location type attribute set, check the Visible checkbox; if you want the attribute to be required, check Required. The Position value is used by the Atlas UI (only). To add the custom attributes to the list, you must first go to Admin > Custom Fields > DataSourceTypes and check the Visible checkbox for the attributes that you want to include. Address STRING[4000] Required if Checked (see Type) City STRING[128] Required if Checked (see Type) State STRING Required if Checked (see Type) Zip STRING[16] Required if Checked (see Type) The street address, city, state, and zip code of the building in which the Data Source is located. The set of valid State values is defined by the USSTATES Component. Building ID STRING[256] Required if Checked (see Type) Floor STRING[256] Required if Checked (see Type) The name or number of the building and floor in/on which the Data Source is located. Contact Name STRING[256] Required if Checked (see Type) Contact Phone STRING[32] Required if Checked (see Type) Contact STRING[256] Required if Checked (see Type) URL STRING[4000] Required if Checked (see Type) The name, phone number, address, and URL of the person who manages or is otherwise responsible for the Data Source. This is particularly useful if the Data Source is managed by a vendor. Location pafield1 STRING[4000] Required if Checked (see Type) Location pafield2 STRING[4000] Required if Checked (see Type) Location pafield3 STRING[4000] Required if Checked (see Type) Location pafield4 STRING[4000] Required if Checked (see Type) Location pafield5 STRING[4000] Required if Checked (see Type) Custom data regarding the Data Source s location characteristics. To present these attributes in the Atlas UI, go to Admin > Custom Fields > DataSourceTypes and check the Visible checkbox. If you check the Required checkbox, a value (here) is required. 25

26 Data Sources IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Organizations STRING[4000] Optional A list of Organizations, given by their pathnames, that the Data Source will be associated with. The individual Organization elements within a pathname are colon-separated, and the paths are pipe-separated; for example: Corporate: HR: Personnel Corporate: Ops: Purchasing Corporate: Admin If you want the Data Source to (also) be associated with the Organization s sub-organizations, add ;y to the end of the path: Corporate: HR: Personnel;y Corporate: Ops: Purchasing;y Corporate: Admin;y I M P O R T A N T I M P O R T A N T The Organization elements must be separated by a colon and a single whitespace (with no whitespace before the colon), as shown in the example. If you re adding the sub-organizations, there mustn t be any whitespace between the semi-colon and the y. Stewards STRING[4000] Required if Checked (see Required Columns and Approval) Discovery Delegates STRING[4000] Required if Checked (see Required Columns and Approval) Lists of Persons who are responsible for managing or collecting data from the Data Source. When the Data Source is added to the Scope of a Request, the Stewards and Discovery Delegates are added, as well. The Persons are identified by their Atlas login IDs and the IDs are pipe-separated; for example: Jim81 hankgadfly BetsyRoss You must specify at least one Steward; Discovery Delegates are optional. See Stewards and Discovery Delegates for more information Data Sources Error Messages The Data Source error messages that are written to the CSV logfile consist, primarily, of errors that announce that a required value is missing, that a named entity doesn t exist, or that a value is badly formatted. If an error was found, a final message is printed: :03:57,022 ERROR - CSV Import was Unsuccessful There s no Import was successful message. If there were no errors, the importer prints nothing to the logfile. 26

27 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Data Sources Data Sources in the Atlas UI PAGE: Map > Data Sources > Select Data Source > Details Details 1 Name 2 Identifier 3 Category 4 Is Global 5 Description 6 Data Source PafieldN 7 Start Data, End Date 8 Custody 9 Status 10 Data Source Comments Data Sources in the Atlas UI Stewardship 11 Organizations (Organization names) 12 Organizations (trailing y designation) 13 Stewards 14 Discovery Delegates 27

28 Data Sources IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Data Sources in the Atlas UI Discovery and Data Management 15 Accessibility 16 Discovery Comments 17 Dicovery CustomN 18 Fixed Collection Cost 19 Media Type 20 Security Level 21 DataManagement Comments 22 DM CustomN 23 Information Type 24 Data Structure Location 25 Country 26 Type 27 Address 28 City 29 State 30 Zip 31 Building ID 32 Floor 33 Contact Name 34 Contact Phone 35 DM CustomN 36 Contact 37 URL 38 Managed By 28

29 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Data Sources 3.2 Related Data Sources CREATE CLASS NAME: Related Data Sources UPDATE CLASS NAME: Related Data Sources PREREQUISITES: Data Sources TEMPLATE: Related Data Sources.csv EMPTY VALUE: NA As an optional part of its definition, you can declare that a Data Source is related to some number of other Data Sources. You create this relationship in order to fully identify the Data Sources that might be involved in the Scope of a Legal Matter. For example, if you have an Archive Data Source that contains messages that are archived from a SharedServer Data Source, you might want to create a relationship between the two Data Sources. Later, when you add SharedServer to the Scope of a Request, you would look at SharedServer s related Data Sources and (possibly) add Archive, as well. (Note that the related Data Sources aren t added automatically.) When you relate two Data Sources, the relationship is two-way: In our example, Archive would show up in SharedServer s Related Data Sources list, and vice versa. The Related Data Sources CSV file lets you create and sever the relationships between Data Sources. Each row in the file identifies the two Data Sources and names the operation that you want to perform, either Create or Delete. The same Data Source can be referred to in more than one row. In the excerpt, below, Archive is related to two other Data Sources, and disassociated from a third: Related Data Sources Data Source,Related Data Source, Comments, Operation Archive, SharedServer, Primary archive, Add Archive, BackupTapes, Physical backups, Add Archive, ITCentral, Decommissioning, Delete Note that there s no update Related Data Sources class. All Data Source relationships are created and severed through the Related Data Sources class Related Data Sources Columns I M P O R T A N T Unless otherwise noted, all string comparisons are case-sensitive. Data Source STRING[250] Required Related Data Source STRING[250] Required These two columns name the Data Sources that will be associated (or disassociated). Both Data Sources must be active (their Status attributes must be set to Active), and the two columns mustn t name the same Data Source. Comments STRING[4000] Optional Comments about the association. 29

30 Data Sources IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Operation STRING Required The operation you want to perform. Valid values are: Add. An association is created between the two Data Sources. Delete. The association between the two Data Sources is severed Related Data Sources Error Messages The Related Data Source error messages that are written to the CSV logfile are consist, primarily, of errors that announce that a required value is missing, that a named entity doesn t exist, or that a value is illegal. If an error was found, a final message is printed: :03:57,022 ERROR - CSV Import was Unsuccessful There s no Import was successful message. If there were no errors, the importer prints nothing to the logfile Related Data Sources in the Atlas UI PAGE: Map > Data Sources > Select Data Source > Related Data Sources 1 Data Source (in the breadcrumb, not shown) 1 Related Data Source 2 Comments 30

31 4 Legal Matter Security and Request Scope 4.1 Matter Security Groups CREATE CLASS NAME: ROLE_MATTERSECURITYGROUP_MAPPING UPDATE CLASS NAME: None PREREQUISITES: Roles and Permissions TEMPLATE: ROLE_MATTERSECURITYGROUP_MAPPING.csv EMPTY VALUE: NA The Matter Security Groups CSV lets you create new Matter Security Groups and assign the Roles that are allowed to access the Matters that are within these groups. You can also add Roles to existing Security Groups. Each row is a combination of a Security Group and a single Role. To add more than one Role to the same Security Group, create multiple rows, one for each Role. The Roles that you specify must already exist Matter Security Groups Columns MATTERSECURITYGROUP_TITLE STRING[2000] Required, Update Key The name of the Security Group. If the Group already exists (case-insensitive), the Role specification is added to the existing Group, otherwise a new Group is created. MATTERSECURITYGROUP_DESC STRING[2000] Optional A human-readable description of the Security Group. This only applies to new Security Groups; if the Security Group already exists, this column is ignored. ROLENAME STRING[250] Required The name (case-insensitive) of a single existing Role. Users who are assigned the Role are allowed to access the Matters that are part of the Security Group that s named in the first column.

32 Legal Matter Security and Request Scope IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Matter Security Groups in the Atlas UI PAGE: Admin > Matter Security Groups > Select a Security Group MATTERSECURITYGROUP_TITLE 2 MATTERSECURITYGROUP_DESC 3 ROLENAME 32

33 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Legal Matter Security and Request Scope 4.2 Add People to Scope CREATE CLASS NAME: Person-RequestScope UPDATE CLASS NAME: None PREREQUISITES: Persons TEMPLATE: Person-RequestScope.csv EMPTY VALUE: NA The Add People to Scope CSV lets you add people to the Scope of a Legal Request. The people that you add can be Atlas users identified by their login IDs or addresses, or they can be Others (people without Atlas accounts) that are identified by address. The Add People to Scope CSV doesn t let you remove people from the Scope of a Request. The Add People to Scope feature is different from the other CSVs: You can enable and disable the ability to import the file by setting the REQUEST SCOPE PERSON IMPORT Component to Enabled or Disabled. By default, Add People to Scope importing is enabled. The UI that imports the CSV is in the Matters module (which we ll look at below) the Admin > Import CSV Data module doesn t recognize the Person-RequestScope class Importing the Add People to Scope CSV The steps, below, tell you how to import an Add People to Scope file. 1 Go to the Matters module, select a Matter and a Request, and click the People in Scope tab. 2 Click Edit, click Others in the Resource Chooser, select the CSV Import radio button, and then click the Click here link to download the Add People to Scope CSV template file. 3 Edit the CSV file to identify the people you want to add to Scope. 4 When you re satisfied with the file, return to the Others tab in the Resource Chooser, click Browse and browse to your file, then click Add in the upper right corner of the Resource Chooser to upload your file. 5 If there s an error, a Click here to download the import log link is displayed on the page (not shown). 33

34 Legal Matter Security and Request Scope IBM Atlas Suite Administrators Guide: Importing Data through CSV Files 6 Click Save & Close to add the file s contents to the Scope of the Request that you re editing Add People to Scope Columns How you populate your Add People to Scope columns depends on the type of person you re adding: If you re adding an Atlas user by login ID, set the value of the LoginID column and leave the rest of the columns empty. If you re adding an Atlas user by address, leave LoginId empty, set the value of the column, provide dummy values for the First Name and Last Name column (they re required, but they ll be ignored), and leave the other columns empty (they ll also be ignored). If you re adding an Other, leave LoginID empty, and supply values for the First Name, Last Name, and columns. The rest of the columns are optional. LoginID STRING[250] Required Identifies, by login ID, the Atlas user that you want to add to the Scope of the Request. The Atlas user must be active. The rest of the columns in the row are ignored. If you don t supply a LoginID value, the First Name, Last Name, and columns are required. First Name STRING[250] Required if LoginID is empty The first name of the Other that you want to add to Scope. If you supply a LoginID value, this column is ignored. Last Name STRING[250] Required if LoginID is empty The last name of the Other that you want to add to Scope. If you supply a LoginID value, this column is ignored. STRING[250] Required if LoginID is empty, Unique The address of the Atlas user or Other that you want to add to Scope. The address must be unique within the Scope of the Request. If the address identifies an Atlas user, the other columns are ignored. If it doesn t identify an Atlas user, a new Other is created and populated with the information given here. If you supply a LoginID value, this column is ignored. DirectoryId INTEGER Optional If the Other is listed in an LDAP system, this is the directory ID of the LDAP server. If you supply a LoginID value, this column is ignored. FullDN STRING[250] Optional If the Other is listed in an LDAP system, this is the distinguished name that leads to the Other s account. If you supply a LoginID value, this column is ignored. Identifier STRING[250] Optional An additional identifier for the Other. This is, typically, a value that uniquely identifies the record that represents the Other in an external database. If you supply a LoginID value, this column is ignored. 34

35 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Legal Matter Security and Request Scope PAField1 STRING[2000] Optional PAField2 STRING[2000] Optional PAField3 STRING[2000] Optional PAField4 STRING[2000] Optional PAField5 STRING[2000] Optional General custom data. The same custom data fields are used for Atlas users and for Others. To present these attributes in the Atlas UI, go to Admin > Custom Fields > Persons and check the Visible checkbox. For Others, custom data is always optional, even if the data is declared to be Required. If you supply a LoginID value, these columns are ignored. 35

36 5 Citations 5.1 Overview A Citation is a reference to a document that contains the rules that govern the retention and disposition of various types of stored content. To understand how to create a Citation object, you need to understand the objects that support Citations: Jurisdictions, Agencies, and GeoNodes Citations, Jurisdictions, Agencies, and GeoNodes Each Citation is associated with a Jurisdiction and an Agency: The Jurisdiction is the Citation s domain, or the area over which it has influence. This area is typically geographical or geopolitical (Asia, Belgium, the European Union, Oregon, as examples). However, you can define your Jurisdictions as you see fit. For example, you can create Jurisdictions that correspond to your company s divisions or business units Eastern Sales Region, Pacific Rim Marketing, Midwest Legal. The Agency is the department within the Jurisdiction that issued or is otherwise responsible for the Citation. The set of Jurisdictions is composed as a flat list (rather than a hierarchy). This makes it easy to create a sensible correspondence between Citations and Jurisdictions, but a flat list isn t terribly friendly for the user: It isn t easy to search, and it doesn t let you describe a group of like elements. For example, let s say you want to find all the Citations that apply to Belgium. You d need to pick through the Jurisdiction list for Belgium, European Union, Council of Europe, and any other Jurisdictions that are applicable. To assist the user in the task of searching for Citations, the system provides GeoNodes. Like Jurisdictions, GeoNodes represent geographical areas (or business units, divisions, and so on), but, unlike Jurisdictions, GeoNodes can be nested to form a hierarchy of areas. For example, the World GeoNode contains Europe which contains Belgium. Each GeoNode is then mapped to one or more Jurisdictions. In our example, the Belgium GeoNode would be mapped to the Belgium Jurisdiction and the European Union and Council of Europe Jurisdictions. With this mapping, a user can quickly find all the Citations that apply to Belgium by using the hierarchical GeoNode browser:

37 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Citations By searching by GeoNode, you can quickly discover all the Citations that are defined by the Jurisdictions to which the GeoNode is mapped The Citation CSV Files The CSV files that you use to create your Citations are listed below, in the order that they must be imported (although, note, the system provides a number of pre-defined objects for most of these classes): The GeoTypes CSV defines labels for the geographical taxonomy that s used in the GeoNode hierarchy. The system supplies GeoTypes for World, Continent, Country/Region, and State. You can augment this set if you wish, although be aware that although every GeoNode must have a GeoType, the GeoType isn t currently used by the system. It s reserved for future use. The GeoNodes and Jurisdictions CSVs create GeoNodes and Jurisdictions. The Jurisdiction Mapping CSV creates the mapping of GeoNodes to Jurisdictions. The Agencies CSV creates Agencies. Finally, the Citations CSV creates the Citation objects themselves. 37

38 Citations IBM Atlas Suite Administrators Guide: Importing Data through CSV Files 5.2 GeoTypes CREATE CLASS NAME: GeoTypes UPDATE CLASS NAME: GeoTypes-update PREREQUISITES: None TEMPLATE: GeoTypes.csv EMPTY VALUE: NULL A GeoType is a label that s attached to a GeoNode. The system provides GeoTypes for World, Continent, Country/Region, and State. GeoTypes are used in the definitions of GeoNodes GeoTypes Columns Name STRING[250] Required, Unique, Update Key The name of the GeoType. Description STRING[4000] Optional A human-readable description of the GeoType. Status STRING Required The state of the GeoType. Valid values (case-insensitive) are: Active. The GeoType can be used in the definition of a GeoNode. Inactive. The GeoType can t be used. PA Field1 STRING[4000] Required if Checked PA Field2 STRING[4000] Required if Checked PA Field3 STRING[4000] Required if Checked PA Field4 STRING[4000] Required if Checked PA Field5 STRING[4000] Required if Checked General custom data. To present these attributes in the Atlas UI, go to Admin > Custom Fields > GeoTypes and check the Visible checkbox. If you check the Required checkbox, a value (here) is required. 38

39 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Citations 5.3 GeoNodes CREATE CLASS NAME: GeoNodes UPDATE CLASS NAME: GeoNodes-update PREREQUISITES: GeoTypes TEMPLATE: GeoNodes.csv EMPTY VALUE: NULL A GeoNode represents a real-world area, such as a continent, country/region, state, or even a business unit or division in your company. For more information on how to construct and use GeoNodes, see Citations, Jurisdictions, Agencies, and GeoNodes GeoNodes Columns Name STRING[250] Required, Update Key The name of the GeoNode. GeoNodes must be unique within the same parent, but different parents can have the same GeoNode child name. For example, you can create a GeoNode named Portland within Maine and another within Oregon. In an update, the Name is combined with ParentGeonode to locate the GeoNode that will be modified. Description STRING[4000] Optional A human-readable description of the GeoNode. ParentGeonode STRING[250] Required, Update Key The name of the GeoNode s parent, expressed as a delimited path starting with World, the topmost node. For example, if you wanted to add a GeoNode to Brazil, you would express the parent thus: World South America Brazil A GeoNode can t act as its own parent, nor can you update a GeoNode so that its parent is one of its own descendants. Status STRING Required The state of the GeoNode. Valid values (case-insensitive) are: Active. The GeoNode can be used in the definition of a Jurisdiction and can be the parent of other GeoNodes. Inactive. The GeoNode can t be used. GeoType STRING[250] Required The GeoNode s type. This must be the name of an exisiting, active GeoType. PA Field1 STRING[4000] Required if Checked PA Field2 STRING[4000] Required if Checked PA Field3 STRING[4000] Required if Checked PA Field4 STRING[4000] Required if Checked PA Field5 STRING[4000] Required if Checked General custom data. To present these attributes in the Atlas UI, go to Admin > Custom Fields > GeoNodes and check the Visible checkbox. If you check the Required checkbox, a value (here) is required. 39

40 Citations IBM Atlas Suite Administrators Guide: Importing Data through CSV Files 5.4 Jurisdictions CREATE CLASS NAME: Jurisdiction UPDATE CLASS NAME: Jurisdiction-update PREREQUISITES: None TEMPLATE: Jurisidictions.csv EMPTY VALUE: NULL A Jurisdiction names a country/region, state, county, business unit or other geographical, political, or corporate domain. By default, the system contains Jurisdiction objects that names most of the countries of the world, the fifty states, the European and African Unions, and so on. For more information on how to construct and use Jurisdictions, see Citations, Jurisdictions, Agencies, and GeoNodes Jurisdictions Columns Jurisdiction STRING[250] Required, Unique, Update Key A name that identifies this Jurisdiction. The name is required and must be case-insensitive unique across all Jurisdictions. Description STRING[4000] Optional A human-readable description of the Jurisdiction. Status STRING Required The state of the Jurisdiction. Valid values (case-insensitive) are: Active. The Jurisdiction can be used in the definitions of other objects. Inactive. The Jurisdiction can t be used. 40

41 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Citations 5.5 Jurisdiction Mapping CREATE CLASS NAME: Jurisdiction-Mapping UPDATE CLASS NAME: Jurisdiction-Mapping PREREQUISITES: Jurisdictions, GeoNodes TEMPLATE: Jurisdiction-Mapping.csv EMPTY VALUE: NULL Before you can use a Jurisdiction in the definition of a Citation, you have to map one or more GeoNodes to it (to the Jurisdiction). The GeoNode acts as a geographical location for the Jurisdiction. The Jurisdiction Mapping CSV file creates and severs the mapping between a GeoNode and a Jurisdiction. Each row in the file identifies a Jurisdiction and a GeoNode, and names the operation that you want to perform, either Add or Delete Jurisdiction Mapping Columns Jurisdiction STRING[250] Required The name of the Jurisdiction. GeoNode STRING[250] Required The name of the GeoNode. Operation STRING Optional The operation you want to perform. Valid values (case-insensitive) are: Add. The GeoNode is mapped to the Jurisdiction. Delete. The GeoNode-Jurisdiction mapping is deleted. If you leave the column blank, the operation defaults to Add. 41

42 Citations IBM Atlas Suite Administrators Guide: Importing Data through CSV Files 5.6 Agencies CREATE CLASS NAME: Agencies UPDATE CLASS NAME: Agencies-update PREREQUISITES: Jurisdictions TEMPLATE: Agencies.csv EMPTY VALUE: NULL An Agency is a department, division, or other governing body within a Jurisdiction. Each Jurisdiction has its own set of Agencies. A combination of Jurisdiction and Agency is required when creating a Citation. During an update, the target Agency is identified as a combination of its name (Name) and Jurisdiction (Jurisdiction) Agencies Columns Name STRING[250] Required, Unique, Update Key A name that identifies this Agency. The name is required and must be case-insensitive unique across all Agencies within the same Jurisdiction (as given by the Jurisdiction column). Description STRING[4000] Optional A human-readable description of the Jurisdiction. Jurisdiction STRING[250] Required, Update Key The name of an existing, active Jurisdiction. In the Jurisdictions CSV, the name is given by the Jurisdiction column. Status STRING Required The state of the Jurisdiction. Valid values (case-insensitive) are: Active. The Agency can be used in the definitions of Citations. Inactive. The Jurisdiction can t be used in the definitions of Citations. 42

43 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Citations 5.7 Citations CREATE CLASS NAME: Citations UPDATE CLASS NAME: Citations-update PREREQUISITES: Jurisdictions, Agencies, GeoNodes TEMPLATE: Citations.csv EMPTY VALUE: NULL A Citation is a law or regulation that governs the use, disposal, security, and so on, of documents. Citations are issued by an Agency within a Jurisdiction Citations Columns Number STRING[2000] Required, Unique, Update Key The Citation s real-world reference number or code. Title STRING[2000] Optional The Citation s name. Jurisdiction STRING[250] Required The name of the Jurisdiction that governs the Citation. In the Jurisdictions CSV, the name is given by the Jurisdiction column. The Jurisdiction must be active, and it must be mapped to a GeoNode. Agency STRING[250] Required The name of the Agency (within the Jurisdiction) that governs the Citation. In the Agencies CSV, the name is given by the Name column. Description STRING[4000] Optional A human-readable description of the Citation. Summary STRING[4000] Optional A human-readable summary of the Citation. Type STRING Optional The type of document that the Citation applies to. The set of valid values is defined by the CITATION CLASS Component; the default set is: Protocol Law/Regulation Opinion/Brief You can create other values by adding Parameters to the CITATION CLASS Component. Reason For Change STRING[4000] Required for Update An explanation of why the Citation is being updated. This column is ignored if you re creating a new Citation. 43

44 Citations IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Details PA Field1 STRING[4000] Required if Checked Details PA Field2 STRING[4000] Required if Checked Details PA Field3 STRING[4000] Required if Checked Details PA Field4 STRING[4000] Required if Checked Details PA Field5 STRING[4000] Required if Checked General custom data. To present these attributes in the Atlas UI, go to Admin > Custom Fields > Citations and check the Visible checkbox. If you check the Required checkbox, a value (here) is required. Specifies Retention BOOLEAN Required A boolean that declares whether the Citation mandates retention: Y means it does, N means it doesn t. Retention on Copies STRING See below Retention on Draft STRING See below Retention on Official STRING See below Sets the Retention Schedule for copies, drafts, and the official version of a record, respectively. See Retention Schedule Values in the Schedules chapter for an explanation of the values that these columns take. If Specifies Retention is Y, these columns are required; if it s N, they re ignored. Dictates Storage BOOLEAN Required A boolean that declares whether the Citation contains storage requirements; Y if it does, N if it doesn t. Storage Notes STRING[4000] Optional A human-readable string that describes the Citation s storage requirements. If Dictates Storage is N, this column is ignored. Dictates Security BOOLEAN Required A boolean that declares whether the Citation contains security requirements; Y if it does, N if it doesn t. Security Comments STRING[4000] Optional A human-readable string that describes the Citation s security requirements. If Dictates Security is N, this column is ignored. Dictates Disposal BOOLEAN Required A boolean that declares whether the Citation contains disposal requirements; Y if it does, N if it doesn t. Disposal Comments STRING[4000] Optional A human-readable string that describes the Citation s disposal requirements. If Dictates Disposal is N, this column is ignored. Limits Use BOOLEAN Required A boolean that declares whether the Citation contains usage requirements; Y if it does, N if it doesn t. Use Restrictions STRING Optional The type of use that s mandated by the Citation. The usage types are Permitted with Restrictions and Prohibited. These types are defined by the system and can t be augmented or modified. If Limits Use is N, this column is ignored. 44

45 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Citations Use Comments STRING[4000] Optional A human-readable string that describes the Citation s usage requirements (in addition to the usage type itself). If Limits Use is N, this column is ignored. Limits Transport BOOLEAN Required A boolean that declares whether the Citation contains transportation restrictions; Y if it does, N if it doesn t. Location Comments STRING[4000] Optional A human-readable string that describes the Citation s restrictions on the locations to which documents can be transported. If Limits Transport is N, this column is ignored. Purposes Comments STRING[4000] Optional A human-readable string that describes the Citation s restrictions on the purposes for which documents can be transported. Transport Requirements STRING[4000] Optional A human-readable string that describes the Citation s other restrictions on the transportation or transferral of a document. If Limits Transport is N, this column is ignored. Requires Disclosure BOOLEAN Required A boolean that declares whether failure to adhere to the Citation s requirements requires disclosure. Disclosure Comments STRING[4000] Optional A human-readable string that describes the Citation s disclosure-of-failure requirements. If Requires Disclosure is N, this column is ignored. Requirements PA Field1 STRING[4000] Required if Checked Requirements PA Field2 STRING[4000] Required if Checked Requirements PA Field3 STRING[4000] Required if Checked Requirements PA Field4 STRING[4000] Required if Checked Requirements PA Field5 STRING[4000] Required if Checked General custom data. To present these attributes in the Atlas UI, go to Admin > Custom Fields > CitationRequirements and check the Visible checkbox. If you check the Required checkbox, a value (here) is required. 45

46 Citations IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Citations in the Atlas UI (Details) PAGE: Citations > Select a Citation > Citation Details 4 Number 5 Title 6 Jurisdiction 7 Agency 8 Description 9 Type 10 Generated by the system 11 Generated by the system 12 Summary 13 Dictates Disposal (if Y) 14 Details PA FieldN 15 Details PA FieldN 46

47 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Citations Citations in the Atlas UI (Requirements) PAGE: Citations > Select a Citation > Requirements 1 Specifies Retention (if Y) 2 Retention on Copies 3 Retention on Drafts 4 Retention on Official 5 Dictates Storage (if Y) 6 Storage Comments 7 Dictates Security (if Y) 8 Security Comments 9 Dictates Disposal (if Y) 10 Disposal Comments 11 Limits Use (if Y) 12 Use Restrictions 13 Use Comments 14 Limits Transport (if Y) 15 Location Comments 16 Purposes Comments 17 Transport Requirements 18 Requires Disclosure (if Y) 19 Disclosure Comments 20 Requirements PA FieldN 21 Requirements PA FieldN 47

48 6 Schedules 6.1 Overview The Schedules CSV files create the objects that define document retention policies and identify the Data Sources that store documents that are governed by these policies. There are four Schedules CSVs: Retention Schedule Events lets you augment the list of events that can be used to define the end of a document s retention period. Schedule Templates are the objects that you use to create a hierarchy of retention policies. There are two types of Templates: Record Classes and Master Schedules. Record Classes are typically used as folders that contain other Record Classes; each branch of the hierarchy (again, typically) culminates in a Master Schedule. Local Schedules are the objects that contain the retention policies that you apply to types of documents (or records ). A Local Schedule is based on, and copies the properties from, a Master Schedule. (It s possible, although atypical, to create a Local Schedules based on a Record Class.) The Local Schedule Record Storage CSV lets you specify the Data Sources that contain the types of records that are governed by a particular Local Schedule Templates and Schedules The Schedule Templates are arranged in a hierarchy in which Record Classes act as folders and Master Schedules are the files. The default COROPORATE Record Class is at the top of the hierarchy; graphically, it looks like this: The hierarchy is purely structural; it doesn t imply any sort of data inheritance. For example, Master Schedule A1 doesn t take on any of the attributes that are defined by Record Class A1.

49 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Schedules The Record Class objects are typically used to represent the business units, departments, divisions, and so on, in your company s organization: Record Class objects are simple: They contain a name, a description, a parent, and not much more there s nothing retention specific about a Record Class. Master Schedules, on the other hand, are the true Schedule Templates. Each Master Schedule identifies a set of record types, defines retention policies, contains references to Citations, and so on. When you create a Local Schedule from a Master Schedule, the information from the Master Schedule is copied into the Local Schedule Special Values The columns that describe a Master or Local Schedule s list of Citations and set of retention policies are more complex than the values for the other columns. The sections, below, explain how to form these values The Citations List Master Schedules and Local Schedules accept a list of Citation specifications through their Citation columns. Each Citation is given in this form: CitationNumber R D M S U T F CitationNumber identifies the Citation. It corresponds to the Number column in the Citations CSV file. The rest of the values are requirements initials that represent the Citation s requirements with regard to this Schedule. They re analogous to the following columns in the Citations CSV: R means the Citation specifies retention requirements. This is analogous to the Citation CSV s Specifies Retention column. D means the Citation specifies disposal requirements (Dictates Disposal). M means the Citation specifies the media on which the document can be stored (Dictates Storage). S means the Citation specifies a security level (Dictates Security). U means the Citation restricts the way a document can be used (Use Restrictions). T means the Citation restricts the way a document can be transported (Limits Transport). F means the Citation requires disclosure of failure (Requires Disclosure). 49

50 Schedules IBM Atlas Suite Administrators Guide: Importing Data through CSV Files If a requirements initial is present in the Citation value, the details of the requirement it represents are applied to the Schedule. In the example Citation value, below, the retention, security, and transport requirements defined by the Fair Use Citation are applied to the Schedule: Fair Use R S T Individual Citation/requirements elements are separated by commas (and no whitespace) in the list: Fair Use R S T,CFR M D,Wash. Rev. Code D T F R As demonstrated by this last example, the requirements initials can be in any order. I M P O R T A N T If you supply a list of Citations, the individual elements must be separated by commas only do not use whitespace after a comma Retention Policy Values Three of the Master Schedule and Local Schedule columns (Retention on Official, Retention on Draft, and Retention on Copies) take a retention policy value that declares how long a record must be retained. A retention policy can be Forever, For five years, Until a certain legal matter is settled, Until a certain legal matter is settled, plus five years, and so on. Within the CSV file, the retention policy value is formed thus: Where: RetentionType Event TimeUnitCount TimeUnit The RetentionType value declares the nature of the amount of time a record must be retained. The possible values are defined by the RETENTIONTYPES Component; the default set is: Not Applicable. The record doesn t have a retention requirement. Permanent. The record may never be dispositioned. Event. The record must be retained until a selected event occurs. Fixed Time. The record must be retained for a given amount of time. Event + Fixed Time. The record must be retained for a given amount of time after a selected event occurs. The set of valid Event values is defined by the Retention Schedule Events CSV file. TimeUnitCount and TimeUnit define a length of time. The former is an integer; the set of valid values is: Day(s) Week(s) Month(s) Year(s) For example, to express Forever, you would use this value: Permanent For five years you would use this: Fixed Time 5 Year(s) 50

51 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Schedules Until a certain legal matter is settled, plus five years is: Event + Fixed Time Conclusion of Matter X 5 Year(s) The three columns that take a retention policy value are required. If a record doesn t need retention policy values, pass in Not Applicable as the retention type: Not Applicable You can also pass in bare delimiters without any values at all. In this case, the Schedule will be marked as Incomplete. Incomplete Schedules can t be approved. I M P O R T A N T If you need to leave a retention policy parameter blank you must separate the delimiters with a single whitespace; for example: Fixed Time 5 Year(s). 51

52 Schedules IBM Atlas Suite Administrators Guide: Importing Data through CSV Files 6.2 Retention Schedule Events CREATE CLASS NAME: Events UPDATE CLASS NAME: None PREREQUISITES: None TEMPLATE: Events.csv EMPTY VALUE: NA The Retention Schedule Events CSV lets you add elements to the Master/Local Schedule s list of Retention Schedule events. These are the events that signal the end of a record s retention period. The events are displayed and assigned through the Event dropdown menu in the Retention Schedule panel at the bottom of the Create Master Schedule and Create Local Schedule pages: The system provides a set of default events: Contract Expiration, Declaration of record, End of Customer Relationship, End of Product Life, Fiscal Year end, and Termination. You can t use the CSV file to remove events from the list. To delete an event, log into Atlas and go to the Admin > Events module Retention Schedule Events Columns Event Name STRING[250] Required, Unique The name of the event that you want to add. Event Type Unused; leave this column empty. 52

53 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Schedules 6.3 Schedule Templates (Master Schedules and Record Classes) CREATE CLASS NAME: Templates UPDATE CLASS NAME: None PREREQUISITES: Retention Schedule Events, Citations TEMPLATE: Templates.csv EMPTY VALUE: NA The Schedule Templates CSV lets you create Master Schedules and Record Classes. These are the template objects upon which you base your Local Schedules. The value of the IsFolder column determines which of the two objects the row will create: Y for Record Classes, N for Master Schedules. If you re creating a Record Class (IsFolder=Y), many of the columns are ignored. N O T E You can only create Schedule Templates through the CSV file you can t modify or delete them Schedule Templates Columns Name STRING[250] Required, Unique for non-country/region Masters The name of the Template that you want to create. Unless you re creating a Country/Region Master Schedule, the name must be unique within the parent Template (which is identified by the Parent Fullname column). For Country/Region Master Schedules, it s expected that the Name value will name an existing Corporate Master Schedule; see the Global Record Name column for more information about the values you use to create a Country/Region Master Schedule. Record Type STRING[2000] Optional Master Schedule only A list of the types of documents (or Record Types ) that are associated with the Template. Each Record Type value is a name of your own invention. Individual elements in the list are pipe-separated; for example: Securities Trusts Logistics and Property Management Payroll The Local Schedules that are based on this Master Schedule will inherit the Record Types listed here, and can associate them with the Data Sources that contain them. Description STRING[2000] Optional A human-readable description of the Template. Parent Fullname STRING[2000] Required The pathname of the Template that acts as the parent of this Template. If you re adding a Template directly under the top node (CORPORATE), the pathname is: CORPORATE If you re adding a Template deeper in the hierarchy, you form the pathname as a colon-separated list of Template names excluding CORPORATE. For example, let s say you want to add a template to Hiring, which is inside of Human Resources, which is inside of CORPORATE. The value of Parent Fullpath would be: Human Resources: Hiring 53

54 Schedules IBM Atlas Suite Administrators Guide: Importing Data through CSV Files The path can contain a mix of Master Schedules and Record Classes although, typically, Record Classes are used to create the hierarchy, while Master Schedules are used as the final leaf in a hierarchy branch: RecordClass1: RecordClass2: RecordClass3: MasterSchedule All the Templates in the path must be approved. Start Date DATE Optional Master Schedule only The day and time that the Master Schedule became or will become effective. End Date DATE Optional Master Schedule only The day and time that the Master Schedule became or will become ineffective. Retention on Copies STRING Required for Master Schedules Retention on Draft STRING Required for Master Schedules Retention on Official STRING Required for Master Schedules Master Schedule only Sets the retention policies for copies, drafts, and the official version of a record, respectively. See Retention Policy Values for an explanation of the values that these columns take. Comments STRING[2000] Optional Further comments about the Template. Citations STRING[2000] Optional Master Schedule only A list of Citations that apply to this Master Schedule. See The Citations List for an explanation of the value that you supply here. Approved BOOLEAN Optional Sets the Template s approval state: Y means it s approved; N or empty means it isn t approved. Only those Templates that have been approved can be used to create Local Schedules. If Automated Workflow is enabled (through the AWF_CONFIGURATION Component), the Template s status is set to Pending regardless of the value, here, and must be manually routed for approval through the Atlas UI. PAField1 STRING[2000] Required if Checked PAField2 STRING[2000] Required if Checked PAField3 STRING[2000] Required if Checked PAField4 STRING[2000] Required if Checked PAField5 STRING[2000] Required if Checked Master Schedule only Custom data. To present these attributes in the Atlas UI, go to Admin > Custom Fields > PolicyTemplate and check the Visible checkbox. If you check the Required checkbox, a value (here) is required. IsFolder BOOLEAN Optional A boolean that declares whether this is a Record Class (Y) or a Master Schedule (N). E-Tags NA Optional Currently unused; leave this column empty. 54

55 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Schedules Code STRING[20] Optional Master Schedule only A short identifier that categorizes the Master Schedule. The set of codes is typically defined by an external system. IsProject NA Optional Currently unused; leave this column empty. Country Code STRING[2] Required for Master Schedules Master Schedule only The two-letter ISO code of the country that this Master Schedule applies to. If you use a code that represents a country/region other than the system default, the Schedule becomes a Country/Region Master Schedule it acts as a country-specific override of a Corporate Master Schedule. If you re creating a Country/Region Master Schedule, you must identify the Corporate Master Schedule(the Schedule that this Schedule will override) in the Global Record Name column. I M P O R T A N T You can t create a Country/Region Master for the system s default country. By default, the system s default country is US. Global Record Name STRING[2000] Required for Country/Region Masters Master Schedule only If you re not creating a Country/Region Master Schedule, you must leave this column empty. If you re creating a Country/Region Master Schedule, this is the pathname of the Corporate Master Schedule that this Schedule will override for the country identified by Country Code. Typically, the Country/Region Master Schedule is given the same name and lives in the same folder as the Corporate Master Schedule for which it s being created. To support this, the Name value needn t be unique for Country/Region Master Schedules. For example, let s say you want to create a Country/Region Master Schedule that overrides the Banking: BNK100, Accounts Master Schedule in Italy. You would (typically) populate the pertinent CSV columns thus: Name: BNK100, Accounts Parent Fullname: Banking Country Code: IT Global Record Name: Banking: BNK100, Accounts Some things to keep in mind: You can t base a Country/Region Master Schedule on another Country/Region Master Schedule it must be based on a Corporate Master Schedule. Also, you can t create a Country/Region Master Schedule all by itself. If you want a Country/Region Master Schedule for which there is no Corporate Master, you have to create a dummy Corporate Master and then base the Country/Region Master on the dummy. You can then delete the Corporate Master (if you want) through the Atlas UI. 55

56 Schedules IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Schedule Templates in the Atlas UI (Record Class) PAGE: Schedules > Classification Library > Select Record Class 1 Parent Fullname 2 Name 3 Generated by the system 4 Description 5 Comments 6 Derived from Approved 7 None 56

57 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Schedules Schedule Templates in the Atlas UI (Master Schedule Details) PAGE: Schedules > Classification Library > Select Master Schedule > Details 1 Name 2 Description 3 None 4 Code 5 Country Code 6 Generated by the system 7 None 8 Derived from Approved 9 Start Date, End Date 10 Comments 11 PAFieldN 12 PAFieldN 13 Record Type 14 Retention on Copies 15 Retention on Drafts 16 Retention on Official 57

58 Schedules IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Schedule Templates in the Atlas UI (Master Schedule Citations) PAGE: Schedules > Classification Library > Select Master Schedule > Citations The Citations UI corresponds to the Citations column value, in the form: CitationNumber R D M S U T F 1 Citations (CitationNumber) 2 Citations (R) 3 Citations (D) 4 Citations (M) 5 Citations (S) 6 Citations (U) 7 Citations (T) 8 Citations (F) 58

59 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Schedules 6.4 Local Schedules CREATE CLASS NAME: Schedules UPDATE CLASS NAME: Schedules PREREQUISITES: Schedule Templates TEMPLATE: Schedules.csv EMPTY VALUE: NULL The Local Schedules CSV creates and updates Local Schedule objects. Each object is based on a Schedule Template. Typically, Local Schedules are based on Master Schedules, only. Note that the Schedules class creates and updates its objects. If the object doesn t exist (based on the Title and Organization Scope columns), it s created; if it does exist, it s updated Local Schedules Columns Title STRING[250] Required, Co-update Key The Local Schedule s name. The name must be unique across all Local Schedule s that have the same Admin Organization (the Organization Scope column). Local Schedules that have different Admin Organizations can have the same name. Organization Scope STRING[2000] Required, Co-update Key The pathname of the Local Schedule s Admin Organization. Individual elements in the pathname are colon/whitespace-separated, starting with Corporate; for example: Corporate: Human Resources: Hiring Description STRING[2000] Optional A description of the Local Schedule. Schedule Scope STRING[2] Optional A token (G, N, or OS) that represents the range of Organizations that the Local Schedule affects: G means it affects all Organizations. The Atlas UI calls this Global, All Organizations. N means it only affects the Organization identified by Organization Scope (Organization, no Sub- Organizations). OS means it affects the Organization identified by Organization Scope plus all of its sub-organizations (Organization, and Sub-Organizations). If you leave the column empty, the scope is set to N (Organization, no Sub-Organizations). 59

60 Schedules IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Record Template STRING[2000] Required for Create The pathname of the Schedule Template upon which this Local Schedule will be based. If you re using the top node (CORPORATE) the path is: CORPORATE If you re using a Template deeper in the hierarchy, you form the pathname as a colon/whitespace-separated list of Template names excluding CORPORATE. For example: Human Resources: Hiring All the Templates in the path must be approved. Record Template: Country Code STRING[2] Required for Create If Record Template is a Master Schedule, this is the Master Schedule s two-letter ISO country code. If Record Template is a Record Class, leave this column empty. Start Date DATE Optional The day and time that the Local Schedule became or will become effective. End Date DATE Optional The day and time that the Local Schedule became or will become ineffective. Office of Records STRING[2000] Required for Approval The pathname of the Organization that s responsible for storing documents that are governed by this Local Schedule. Individual elements in the path are colon-separated; for example, Corporate: Human Resources: Personnel.If you re attempting to auto-approve the Schedule (by setting Approved to Y), this column is required; otherwise, it s optional and the Schedule is marked as Incomplete. Records Coordinator STRING[250] Required for Approval The login ID of the Person who acts as coordinator for the Local Schedule. If you re attempting to auto-approve the Schedule (by setting Approved to Y), this column is required; otherwise, it s optional and the Schedule is marked as Incomplete. Retention on Copies STRING See below Retention on Draft STRING See below Retention on Official STRING (Probably) Required for Approval Sets the Retention Schedule for copies, drafts, and the official version of a record, respectively. See Retention Schedule Values for an explanation of the values that these columns take. If you re attempting to auto-approve the Schedule (by setting Approved to Y), at least one column is required; typically, the Retention on Official column is required, but it depends on how your system is set up. See the the LOCAL_SCHEDULE_APPROVAL_RULES Component for details. If you don t supply at least one column, the Schedule is marked as Incomplete. Citations STRING[2000] Optional A list of Citations that apply to this Local Schedule. See The Citations List for an explanation of the value that you supply here. 60

61 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Schedules Comments STRING[2000] Optional Comments about the Local Schedule. Code STRING[20] Optional A short identifier that categorizes the Local Schedule. The set of codes is typically defined by an external system. PAField1 STRING[2000] Required if Checked PAField2 STRING[2000] Required if Checked PAField3 STRING[2000] Required if Checked PAField4 STRING[2000] Required if Checked PAField5 STRING[2000] Required if Checked Custom data. To present these attributes in the Atlas UI, go to Admin > Custom Fields > PolicySchedule and check the Visible checkbox. If you check the Required checkbox, a value (here) is required. Approved BOOLEAN Optional Sets the Schedule s approval state: Y or empty attempts to set the state to Approved. N sets it to Pending if the Required for Approval columns are populated and Incomplete if they aren t. If Automated Workflow is enabled (through the AWF_CONFIGURATION Component), the Schedule is set to Pending or Incomplete, regardless of the value of this column. Similarly, if the Schedule must be mapped to a Data Source (as set through the LOCAL_SCHEDULE_APPROVAL_RULES Component), the status is set to Pending or Incomplete. In this case, you can auto-approve the Schedule by importing the mapping through a Local Schedule/Data Source Mapping CSV with the Approved column (in that CSV) set to Y. Tag STRING[2000] Optional An additional identifier for the Local Schedule. Reason for Change STRING[4000] Required for Update If you re updating a Local Schedule, you must supply a reason for the change in this column. If you re creating a Local Schedule, the column is ignored. 61

62 Schedules IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Local Schedules in the Atlas UI (Details) PAGE: Schedules > Local Schedule > Select Local Schedule 1 Title 2 Record Template 3 Derived from Record Template 4 Description 5 Code 6 Tag 7 Schedule Scope 8 Organization Scope 9 Generated by the system 10 Derived from Record Status 11 Start Date, End Date 12 Office of Records 13 Records Coordinator 14 Comments 15 PafieldN 16 PafieldN 17 PafieldN 18 Retention On Copies 19 Retention on Drafts 20 Retention on Official Local Schedules in the Atlas UI (Citations) See Schedule Templates in the Atlas UI (Master Schedule Citations). 62

63 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Schedules 6.5 Local Schedule/Data Source Mapping CREATE CLASS NAME: Schedule_Mapping UPDATE CLASS NAME: Schedule_Mapping PREREQUISITES: Local Schedules, Data Sources TEMPLATE: Schedule_Mapping.csv EMPTY VALUE: NULL The Local Schedule/Data Source Mapping CSV identifies the Data Sources that store the various documents (or Records) that are goverened by a Local Schedule. Within the same CSV file you can create, modify, and sever the mapping between a Local Schedule and its Data Sources. You specify the operation you want to perform in the Operation column. The identify of a Local Schedule/Data Source Mapping object is a combination of the Title, Organization Scope, Record Type, and Record Type: Document Type columns Local Schedule/Data Source Mapping Columns Title STRING[250] Required, Co-update Key The Local Schedule s name. Organization Scope STRING[2000] Required, Co-update Key The pathname of the Local Schedule s Admin Organization. Individual elements in the path are colon-separated; for example: Corporate: Sales: Midwest I M P O R T A N T The Organization names in the pathname must be separated by a colon and a single whitespace (with no whitespace before the colon), as shown in the example. Record Type STRING[2000] Required, Co-update Key A string that names the type of record that s stored on the Data Source ( Rental Agreement, Employment Contract, Environmental Study, as examples). There s no set list of Record Types. If the Type doesn t exist, it s created. Record Type: Annotation STRING Optional Additional information about the Record Type. Record Type: Document Type STRING Required, Co-update Key A token that denotes the version of the Record that s stored on the Data Source. The set of valid tokens, below, is defined by the system and can t be augmented or modified. Official. The official version of the Record. Drafts. Versions of the Record that are in draft form, that are obsolete, and so on. Copies. Copies of the official version of the Record. 63

64 Schedules IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Data Sources STRING[2000] Required The names of the Data Sources that store the Records that are described by the Record Type and Record Type: Document Type columns. The Data Source names are pipe-delimited; for example: Shared Server Server Tape Backup Record Type: Security Classification STRING Required The level of security that should be used for documents of this type. The set of valid values is defined by the SECURITYLEVEL Component; the default set is: Confidential Internal Personally Identifiable Information Public Restricted You can create other values by editing the SECURITYLEVEL Component. Record Type: Media Type STRING Required The media that stores documents of this type. The set of valid values is defined by the MEDIATYPES Component; the default set is: Electronic Paper/Physical Electronic and Paper/Physical You can create other values by editing the MEDIATYPES Component. Approved BOOLEAN Optional Sets the object s approval state: Y means it s approved; N or empty means it isn t approved. If Automated Workflow is enabled (through the AWF_CONFIGURATION Component), the object s status is set to Pending and must be (manually) routed for approval through the Atlas UI. Reason for Change STRING[4000] Required on Update The reason this object is being updated. Operation STRING Optional If you want to create or modify the object, leave this column empty. If you want to delete the object, set the value to Delete. 64

65 IBM Atlas Suite Administrators Guide: Importing Data through CSV Files Schedules Local Schedule Record Storage in the Atlas UI PAGE: Schedules > Classification Library > Select Record Class > Record To Repository Matrix 1 Title 2 Record Type 3 Record Type: Annotation 4 Record Type: Document Type 5 Data Sources 6 Record Type: Security Classification 7 Record Type: Media Type 65