IBM. Bulk Load Utilities Guide. IBM Emptoris Contract Management SaaS

Transcription

1 IBM Emptoris Contract Management IBM Bulk Load Utilities Guide SaaS

2

3 IBM Emptoris Contract Management IBM Bulk Load Utilities Guide SaaS

4 ii IBM Emptoris Contract Management: Bulk Load Utilities Guide

5 Copyright Note: Before using this information and the product it supports, read the information in Notices on page 57. Copyright IBM Corporation 2012, All rights reserved. Copyright Emptoris 1999, All rights reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GS ADP Schedule Contract with IBM Corp. Copyright IBM Corp. 2012, 2016 iii

6 iv IBM Emptoris Contract Management: Bulk Load Utilities Guide

7 Contents Copyright iii Chapter 1. About this Guide Chapter 2. Introduction to Bulk Load Utilities Chapter 3. Downloading Bulk Load Utilities Toolkit Chapter 4. Standard Loader Standard Loader Features Excel File Input Data Contract Template Attachments Security Permission Grants and Terms Terms Error and Status Log Data Loading Prerequisites for the Standard Loader 9 Configuration of Value Lists Setting Permissions Preparation of Input files Loading data with the Standard Loader Creating a Job from the UI Creating a Job from the CLI Reviewing the Import Job Results and Error Logs 29 Status of Contracts uploaded by using the Standard Loader Dealing with Lines that Failed to Upload Editing, Saving and Uploading the Line Upload Error File Chapter 5. Fast Loader Fast Loader Components Staging Tables Stored Procedures Control File and SQL File CSV Files Input for Other Applications Logs and Errors Data Loading with Fast Loader Using the DB2 database Data Loading Specifications for Objects Contract Lines Object Data Loading Contract Terms Object Data Loading Product Object Data Loading Custom Property Object Data Loading Appendix. Time Zones Notices Copyright IBM Corp. 2012, 2016 v

8 vi IBM Emptoris Contract Management: Bulk Load Utilities Guide

9 Chapter 1. About this Guide The IBM Emptoris Contract Management Bulk Load Utilities enable an IBM Emptoris Customer to load data from external applications or sources in to Emptoris Contract Management. These utilities can be used to load contract data or legacy contracts of any category, Buy (Purchase Agreement), Sell (Sales Agreement) or Other, in bulk quantities. Introduction This publication provides an overview of the Bulk Load Utilities, the Standard Loader, and the Fast Loader. It also provides information on how to administer and configure Emptoris Contract Management in preparation for data loading, and the details of specifications and file formats for loading data. Where to find information This following table describes the contents of the guide. Table 1. Chapters in the Bulk Load Utilities Guide Chapter Standard Loader Fast Loader Description Provides information on the following topics: Overview of Standard Loader, permissions, data loading prerequisites, and running the utility. Provides information on the following topics: Overview of the Fast Loader, Fast Loader components, and data loading. Copyright IBM Corp. 2012,

10 2 IBM Emptoris Contract Management: Bulk Load Utilities Guide

11 Chapter 2. Introduction to Bulk Load Utilities Each of the Bulk Load Utilities provides distinct features to enable bulk loading of contract data. Standard Loader The Standard Loader supports data input through Excel files. Information that is contained in these files is integrated to create, update, or delete objects in Emptoris Contract Management. The Excel document is uploaded as part of an HTTP multipart request. On the Emptoris Contract Management application server, the HTTP request is transformed into an import job. The scheduling and execution of the import job is handled by a job scheduler. Upon job execution, the input data file is parsed and each row in the file is processed. The success or failure result for each row is stored in a text file as a job attachment. The data must be captured in a specified file format before the load process. Fast Loader The Fast Loader is an SQL-based bulk load utility that you can use to load high volumes of data from previously used applications to Emptoris Contract Management. This utility is ideal for fast and efficient loading of contract data on both a non-recurring (initial load) and recurring (periodic loads) basis. The Fast Loader uses staging tables to maintain process results and errors that are associated with each Fast Loader job. The staging tables are pre-defined, and ensure that the Emptoris Contract Management data model is not directly exposed to other applications. Comparison between the Standard Loader and the Fast Loader The following table compares the actions supported by the Standard Loader and the Fast loader. Table 2. Comparison between the Standard Loader and the Fast Loader Upload method Standard Loader From UI and from the Command line Fast Loader Input data format Excel only CSV only Contracts (with terms, parties, and lines) Create Command line only Not supported Contract Parties Add, Update, and Delete Not supported Contract Lines Add, Update, and Delete Add, Update, and Delete Contract Terms Add, Update, and Delete Add, Update, and Delete Products Create, Update, and Delete Create, Update, and Delete Custom Properties (for Contracts, Products, or Organizations) Update Value and Delete Value Update Value and Delete Value Copyright IBM Corp. 2012,

12 Note: You can administer individuals, users, organizations, and user groups only from the IBM Emptoris Strategic Supply Management Platform. For information about batch uploads for individuals, users, organizations, and user groups, see the IBM Emptoris Strategic Supply Management Platform Administrator Guide. 4 IBM Emptoris Contract Management: Bulk Load Utilities Guide

13 Chapter 3. Downloading Bulk Load Utilities Toolkit You can download the Bulk Load Utilities toolkit from the IBM Emptoris Contract Management application. About this task The Bulk Load Utilities toolkit contains the following files. v For the Standard Loader: blu.tar v For the Fast Loader: fl_sdks.tar Procedure To download the Bulk Load Utilities toolkit, complete the following steps: 1. From the IBM Emptoris Contract Management application, go to the Administration List page. Under Application, click System Settings > Job List. Click BLU Toolkit. 2. Save the BulkLoadUtilities.zip file. 3. You can also access the Bulk Load Utilities files from the application server. Go to the folder /opt/emptoris/repository/packages/ecm_<release&buildnumber>/ application and copy the blu.tar and the fl_sdks.tar files. Copyright IBM Corp. 2012,

14 6 IBM Emptoris Contract Management: Bulk Load Utilities Guide

15 Chapter 4. Standard Loader The Standard Loader provides additional functionality by enabling customers to load legacy or other contract data into Emptoris Contract Management. Data must be captured in the specified file format before you can load the data. The sequence of data in each input file must exactly follow the specifications that are provided. Note: The Standard Loader supports only Excel files for data input. The Standard Loader is supported on Windows and UNIX environments. Overview of the Standard Loader Data Loading Process The following illustration highlights the process of loading and initializing contract data through the Standard Loader. Standard Loader Features The Standard Loader is an HTTP and Enterprise Java Beans-based utility that you can use to load contracts and other data into Emptoris Contract Management in bulk quantities. Excel File Input Data The data must be input by using only Excel files. The files contain fields in a required sequence. For more information, see Preparation of Input files on page 11. The Standard Loader processes the data based on the standard fields defined for a data input file even if the data in the header row is invalid or incorrect. Contract Template You can specify a contract template for a contract by including the name of the contract template in the contract input file. Copyright IBM Corp. 2012,

16 You must specify a contract template when you create the following types of contracts: v Authored contract. v Authored amendment. v Contract with lines. v Filed contract that includes the mandatory properties of terms. Consider the following points for using a contract template: v The contract template must exist in Emptoris Contract Management. It must be active, suitable for the type of contract that is created, and match the category that is specified in the contract data input file. v If you want to add contract lines to the contracts, choose a contract template that contains line definitions. After the contracts are loaded, you can add lines to them using these line definitions. v A contract template can also supply more properties such as Folders, Events, and Security. v If a contract template specifies one or more folders, the input contract is loaded to those folders in the Emptoris Contract Management Repository. v If a contract template specifies one or more events, these events can be enabled by dates in the contract. In this way, you can supply a date property or term through the contract data input file, and this date can be used to initiate a notification from an event after the contract is loaded. Attachments An attachment can be a scanned contract image, Microsoft Word document, or any other file that is associated with a contract. Consider the following points for uploading attachments: v The default file size limit for an attachment is 10 MB and increasing the limit beyond 10 MB is not certified. Note: An attachment larger than 10 MB can cause response time issues and can also cause the keyword search index process or the presentation to fail. v The combined size of all the attachments must be less than or equal to 100 MB. v The size of attachments is controlled by the system property multipart.max.part.size in the ecm.properties file. v The maximum size of the import when you are using the Standard Loader is 2 GB. This maximum import size for all attachments is a limitation of the import protocol and cannot be increased. v The visibility of attachments is set through Boolean values. The default value is true. v If the attachment.extension.filtering property is set to true, you can only upload attachments with file extensions that are specified by the attachment.extension.list and the attachment.extension.list.type properties. If the attachment has an invalid extension, a job is not created. Note: If more than one application server is connected to a database schema, the DMS directory must be shared. Otherwise, attachments that are created by one application server cannot be accessed by the other application server. This applies to contract attachments and job attachments. The DMS directory is the root folder of the Emptoris Contract Management file repository. This path is specified during installation as the File Repository Location. 8 IBM Emptoris Contract Management: Bulk Load Utilities Guide

17 Security Permission Grants and Terms Emptoris Contract Management security applies to all objects that are loaded by using the Bulk Load Utilities. Terms You can associate users to contracts by granting permissions. For more information, see Setting Permissions on page 10. When you load contract data, you specify the user-defined term definitions to add to all contracts, and the corresponding term values for each contract. Consider the following points for the term definitions: v The specified term definitions must exist in Emptoris Contract Management. v System terms apply to all contracts automatically. For example, Contract Class, Region, and Execution Date. v Each System Term reflects the value of a corresponding contract property. Hence, you cannot update system terms by using Bulk Load Utilities. Error and Status Log The utility implements error handling to check for potential load problems before the contract is loaded. A status summary message appears at the end of the load process. The utility writes all erroneous records to specific job attachment files to facilitate data reconciliation for a subsequent load. Data Loading Prerequisites for the Standard Loader To ensure trouble-free data transfer, you must configure some Emptoris Contract Management objects before you upload the data. You must complete the following steps before you start the data loading process. v Configure the following Emptoris Contract Management objects: Contract Classes Value Lists Term Definitions Contract Templates v Grant required permissions to the users. v Prepare the input files as specified. Configuration of Value Lists Use the Value Lists feature within the Emptoris Contract Management Administration to define the values in the value lists. After you define the value lists and the values, you can specify the values in the input files for the Standard Loader for the property of an object that uses the value list. Consider the following points for configuring the value lists. v The values that are submitted in the Excel file match the values that are defined in Emptoris Contract Management for the following value lists: For Organizations - Currency. For Contracts - Region and Contract Substatus. Chapter 4. Standard Loader 9

18 v Before you load the data, modify the value lists to reflect the values that are required by the IBM Emptoris Customer. Setting Permissions In Emptoris Contract Management, permissions are applicable to all activities within the application. For more information about Security Administration and permissions that are required, see the IBM Emptoris Contract Management System Administration Guide. Permissions for creating contracts Permissions are granted to the specific internal user in one of three ways automatically, depending on whether a contract template is specified or whether class-level permissions are applicable in Security Manager. The following permissions are required by the internal users to upload contracts. You must assign the required permissions within the Security Manager feature in Emptoris Contract ManagementAdministration before you load the input file. v Contract permissions: Contract Template > Read Contracts > Filed > Create Contracts > Quote > Create Contracts > Authored Contract > Create Contracts > Authored Amendment > Create v In addition to permissions within the new contract instance, the internal contact that is specified in the Contracts.xls file must have permission to create filed contracts. v The permissions that are granted to the specified internal user must include permissions for all activities that are done in the contract loading process. For example, if attachments or terms are added to the contract by the Bulk Load Utilities, permissions to add these objects must be applicable to the internal contact specified in the Contracts.xls file. Otherwise, the contract creation process cannot be completed. v The internal contact must have permission to read each contract template or user-defined term definition. v When you create an amendment, Read permission for the base contract is also required. Permissions for the created contract instance The following permissions are granted when you create a contract. v If a contract template is specified in the Contracts.xls input file, the resulting contract inherits the Contracts Security List specified within that contract template. All permissions that are granted to users and user groups are copied to the contract instance. v The Contracts Security List of a contract template includes a Creator token. Any permissions that are granted to this token are automatically granted to the internal contact specified in the Contracts.xls file when the contract is created. v If a contract template is not specified for the contract in the input file, the internal contact that is specified in the Contracts.xls file is automatically granted the Contract Creator permission group for the resulting contract. 10 IBM Emptoris Contract Management: Bulk Load Utilities Guide

19 v If the internal contact specified in the Contracts.xls file is listed in Security Manager and granted class-level permissions to the Contract object, these permissions are implied within the security list of all resulting contracts. Permissions for adding, updating, or deleting objects in a contract To add, update, or delete objects in a contract, you must have the required permissions for the objects. For more information, see the IBM Emptoris Contract Management System Administration Guide. You might also require some other permissions based on the object and the action. v You must have the Read permission for the contract that is being updated. v For actions on language terms, you must have the Read permission for the contract language. v For actions on tracking terms in an Executed contract, you must have the Contract > Update Executed Contract > Perform permission. Permissions for products To create, update, or delete products in the Emptoris Contract Management application, you must have the required permissions as specified in the IBM Emptoris Contract Management System Administration Guide. Preparation of Input files Data is loaded into Emptoris Contract Management in the form of Excel files. The files contain fields in a required sequence. This sequence is important because some objects reference other existing objects. The fields that are supplied in each input Excel file must match the order, length, and other requirements specified. Note: If multiple files are uploaded, they must be uploaded in the sequence that is given in the table. The following table lists the input files that are required and the sequence of uploading for the various actions for the Standard Loader. Table 3. Standard Loader Actions Action Create Contract Create Contract with Parties Create Contract with Lines Create Contract with Parties and Lines Add, Update, or Delete Contract Parties Add, Update, or Delete Contract Lines Add, Update, or Delete Contract Terms Files contracts.xls 1. contracts.xls 2. parties.xls 1. contracts.xls 2. lines.xls 1. contracts.xls 2. parties.xls 3. lines.xls parties.xls lines.xls terms.xls Chapter 4. Standard Loader 11

20 Table 3. Standard Loader Actions (continued) Action Create or Update Products Update or Delete the Custom Property values (for Contracts, Products, or Organizations) Files products.xls customproperties.xls Contract Data Input File Use the contract data input file, contracts.xls, to create contracts in Emptoris Contract Management. Consider the following points for the data in the contract data input file: v You can add only one owning organization, one affiliated organization, and one contract relationship in the Contract data file. v To add multiple internal and external parties to a specific contract or all contracts that are listed in the contract data input file, upload the party data input file (parties.xls) along with the contract data. v To add contract lines to a specific contract or all contracts that are listed in the contract data input file, upload the line data input file (lines.xls) along with the contract data. v If the Contract Row Reference that is provided in the parties.xls file or the lines.xls file does not match any contract from the contracts.xls file, the party or line is not added to any contract. The status of the job is set as Completed. v If the Organization (Internal, Owning or Affiliated) Name and Number fields contain a non-null value, the system uses these values in combination to identify the organization. If the field values do not correspond to a valid internal organization, an error results and the contract is not created. v If the field values for the Contract Relationship do not correspond to a valid relationship and contract, an error results and the contract is not created. v The default file size limit for an attachment is 10 MB. v The combined size of all the attachments must be less than or equal to 100 MB. v You can add only those terms that are already created in the Emptoris Contract Management application. You cannot create term definitions in the application by using the Fast Loader. v The date format of each term is configured in Emptoris Contract Management. In addition to data type constraints, term definitions can also have entry type constraints. If a term definition has an entry type of List of Values or Both, ensure that the values that you specify in the contract data input file match the existing values. v Term values are case-sensitive. To view a sample contract data input file, see the contracts.xls file that is provided with the blu.tar file. 12 IBM Emptoris Contract Management: Bulk Load Utilities Guide

21 Fields in the Contract data file The following table lists the fields for the contract data input file. Table 4. Contract Data Field No. Field Name Max. Length Required Comments 1 Contract Origin Y Can be an Authored Contract, Filed Contract, Authored Amendment, Filed Amendment, or a Quote. 2 Contract Name 128 Y 3 Contract Title 128 Y If a contract template is specified, the contract title that is specified in the contract template is used. 4 Notes N Notes 5 Contract Class 50 Y if the status of the contract is Executed. N if the status of the contract is Draft. Value must match an existing contract class in Administration. If the value for this field is provided, the contract class that is specified in the contract template is ignored. 6 Substatus 50 N Value must match a value in the Contract SubStatus value list. 7 Contract Category 50 Y Must be Buy, Sell, or Other. (Buy = Purchase Agreement; Sell = Sales Agreement; Other = Other.) If a contract template is specified, this value must correspond to the contract category specified in the contract template. 8 Region 50 N Value must match a value in the Region value list. 9 Effective Start Date 10 Effective End Date Date Y This field is left as null when no value is provided and the time defaults to 00:00:00. Date N This field is left as null when no value is provided and the time defaults to 00:00: Execution Date Date Y If this field is left blank, status for the created contract is Draft. If no time value is provided, the time defaults to 00:00:00. If the execution date is entered, then the External Party Unique ID or the External Party ID must be provided. Chapter 4. Standard Loader 13

22 Table 4. Contract Data (continued) Field No. Field Name 12 External Party Unique ID Max. Length Required Comments Number N The ID for the primary external party. The unique ID for the external organization as generated in the Emptoris Strategic Supply Management Platform. 13 External ID 50 Y The ID for the primary external party. 14 Internal Contact Login 15 Contract Template Name 16 Legal View Attachment 17 Attach Template Language 18 Amendment Reference 19 Quote Start Date 20 Quote End Date 21 Contract Comments The identifier of an external organization or individual. String Y The user name of the internal contact of this contract. This value determines the Contracting Organization, Owning Organization, and Internal Party of the contract. 128 N Mandatory for authored contracts and authored amendments. Value must match an existing contract template name in Administration. N Contract attachment for filed contracts and quote contract only. Boolean N Attach template language to a new amendment. String Date Date N Mandatory for an amendment contract. N Mandatory for a quote contract. N Mandatory for a quote contract. If the contract that is being amended exists in the system, use the as the value for this field. Specify in the format #REF: <row number>. For example, if the contract that is being amended is created in row number 2, enter #REF:2. Defaults to current date if not supplied. If no time value is provided, the time defaults to 00:00:00. This field is left as null when no value is provided. If no time value is provided, the time defaults to 00:00: N Adds a comment to the contract. 14 IBM Emptoris Contract Management: Bulk Load Utilities Guide

23 Table 4. Contract Data (continued) Field No. Field Name 22 Internal Party Name 23 Internal Party Number 24 Owning Organization Name 25 Owning Organization Number 26 Affiliated Organization Name 27 Affiliated Organization Number 28 Contract Relationship Max. Length Required Comments String N The name of the organization of the Internal Contact for this contract. String N The organization number for the organization of the Internal Contact for this contract. String N The organization that is identified as the owning organization. String N The organization number for the owning organization. String N The name of the organization that is identified as the affiliated organization. String N The organization number for the affiliated organization. String N Identifies the contract relationship between the contract that is being created and another contract. Must contain a non-null value if the Contract Number field contains a non-null value. The system uses these values in combination to establish a relationship between the identified contract and the new contract that is being created. The value of the To Label field of Relationship (Relationship Types in the Administration UI) is considered here. If this contract is related to another contract from the same contracts.xls file, then enter the row number from the contracts.xls file that represents the contract to which this contract is related. Note: Relationships are created automatically for amendments. You cannot create amendment relationships by using the Relationships column. Chapter 4. Standard Loader 15

24 Table 4. Contract Data (continued) Field No. Field Name 29 Related Contract Number Max. Length Required Comments String N The contract number of the contract that is related to this new contract. Must contain a non-null value if the Contract Relationship field contains a non-null value. The system uses these values in combination to establish a relationship between the identified contract and the new contract that is being created. Note: Relationships are created automatically for amendments. You cannot create amendment relationships by using the Relationships column. 30, x Term Values N Specify valid values for each term for the contracts that is being created. x means x number of columns after column number 31. Note: The Term Values field must be preceded by any of the fields that are mentioned till field number 29 in this table. The contracts.xls file contains the contract-attachments sheet that includes data for contract attachments. The following fields are available in the contract-attachments sheet: Table 5. Attachment Data Field No. Field Name 1 Contract Row Reference Max. Length Required Comments Y Row number from the contracts.xls file that represents the contract to which you want to add this attachment information. If no value is supplied, the attachment is added to all contracts in the contracts.xls, which are successfully created. For example, if the value of this field is 4, the attachment information is added to the contract that is listed in the fourth row of the contract data input sheet. 16 IBM Emptoris Contract Management: Bulk Load Utilities Guide

25 Table 5. Attachment Data (continued) Field No. Field Name 2 Attachment File Name Max. Length Required Comments Y If you run the job from the application, you must provide the name of the attachment along with the extension. If you run the job from the command prompt, you must provide the relative path for the file. 3 Attachment Visibility 4 Attachment Class 5 Attachment Description 6 Attachment Start Date 7 Attachment End Date Y Y Input values are Visible to all or Visible only to internal parties. Note: The input for attachment visibility is case-sensitive. You must enter a class value that is available for the value list AttachmentClass in Administration > Configuration > Value List Y Attachment description. Signifies the date from when the attachment is valid. Note: The start date must be an earlier date than the end date. Signifies the date till when the attachment is valid. Note: The end date must be a later date than the start date. Party Data Input File Use the Party Data Input file (parties.xls) to add, update, or delete the parties for a contract. The parties include the internal parties, external parties, affiliated organizations, and owning organizations. You can also add a contact or delete a contact from the contract. To add the contract parties when you create the contract, upload the parties.xls file along with the contracts.xls file. Consider the following points for the data in the party data input file: v If the External Party Unique ID field contains a non-null value, the system uses that value to identify the organization. If the field is null, then the system uses the Party External ID to identify the organization. If both the External Party Unique ID and Party External ID are null, then the system uses the Party Name and Party Number values in combination to identify the organization. v You cannot update or delete the Internal Parties and External Parties for a contract when you create a contract by using the contracts.xls and the parties.xls files. v If the Contract Row Reference that is provided in the parties.xls file does not match any contract from the contracts.xls file, the party is not added to any contract. The status of the job is set as Completed. v For an Affiliated Organization or an Owning Organization, you must provide the Party Name and the Party Number. Chapter 4. Standard Loader 17

26 v If multiple Affiliated Organizations are present in the input file for the same contract, all valid organizations are added to the contract. v You cannot delete the Owning Organization for a contract. v If multiple Owning Organizations are present in the input file for the same contract, the organizations are overwritten and the last organization is present in the contract as the Owning Organization. v If the Owning Organization is provided in both the contracts.xls and the parties.xls files for the same contract, then the Owning Organization that is provided in the contracts.xls file is overwritten by the Owning Organization that is provided in the parties.xls file. v You cannot delete the primary contact for a party. v When you add a party to the contract with the role as primary, the contact for the party is added to the contract as the primary contact for the party. To retain the primary contact from the previous party with the primary role, set the Retain the Primary Contact from the Previous Party field to Y (Yes). v When you add an internal or external party to a contract along with the party role, if the party role does not match any role in the application, the party is added to the contract without a role. To view a sample party data input file, see the parties.xls file that is provided with the blu.tar file. Fields in the Party data file The following table lists the fields for the party data input file. Table 6. Party Data Field No. Field Name 1 Contract Row Reference Max. Length Required Comments 10 N Row number from the contracts.xls file that represents the contract to which you want to add this party information. 2 Contract Number 10 N Mandatory if you are uploading the parties data separately. If no value is supplied, the party is added to all contracts specified in the contracts.xls file. For example, if the value of this field is 4, the party information is added to the contract that is listed in the fourth row of the contract data input file. Identifies the Contract Number of the contract for the party. 18 IBM Emptoris Contract Management: Bulk Load Utilities Guide

27 Table 6. Party Data (continued) Field No. Field Name Max. Length Required Comments 3 Action 1 Y Valid action types include AddOrganization, UpdateOrganization, DeleteOrganization, AddOtherContact, and DeleteOtherContact. 4 Party Name 100 Y Name of the Individual or Organization. 5 Party Type 100 Y Can be InternalParty, ExternalParty, AffiliatedOrganization, or OwningOrganization. 6 Party Number 30 Y Party Number 7 Party External ID 8 External Party Unique ID 50 N Unique number of the external Organization or Individual. Number N The unique ID for the external organization as generated in the Emptoris Strategic Supply Management Platform. 9 Role 30 N Role that is assigned to the party 10 Signatory 10 N Number of signatories 11 Retain the Primary Contact from the Previous Party N Retain the primary contact of the contract. The accepted values are Y (Yes) or N (No) 12 Contact Login 50 N User name of the primary contact of the internal party. 13 Contact External ID 50 N External ID of an individual Line Data Input File Use the Line Data Input file (lines.xls) to add, update, or delete the lines from a contract. To add the contract lines when you create the contract, upload the lines.xls file along with the contracts.xls file. If the Contract Row Reference that is provided in the lines.xls file does not match any contract from the contracts.xls file, the party or line is not added to any contract. The status of the job is set as Completed. To view a sample line data input file, see the lines.xls file that is provided with the blu.tar file. Chapter 4. Standard Loader 19

28 Fields in the Lines data file The following table lists the fields for the line data input file. Table 7. Line Data Input File fields Field No. Field Name 1 Contract Row Reference 2 Contract Number Max. Length Required Comments 10 N Row number from the contracts.xls file that represents the contract to which you want to add this line information. 10 N Mandatory if you are uploading the lines data separately. If no value is supplied, the line is added to all contracts specified in the contracts.xls file. For example, if the value of this field is 4, the line information is added to the contract that is listed in the fourth row of the contract data input file. Identifies the Contract Number of the contract for the line. 3 Action 1 Y Valid action types include C (Create), U (Update), and D (Delete). 4 Line Number 10 N 5 Line Type Name 6 Price List Name Mandatory if you are updating or deleting the lines. Visible number of the line in the contract. 30 Y The line definition name. Note: The Line Type Name is case-sensitive. 300 N Name of the price list 7 Product Name 300 N Name of the product. 8 Product Number 300 N The product number. 9 Quantity N The quantity for the product. 10 Unit List Price Float N Unit list price of the product that is selected in the line. 11 Discount Percent 12, x User-defined data definitions Float N Percent of discount to be applied to Line. N The user-defined data definitions in the line. 20 IBM Emptoris Contract Management: Bulk Load Utilities Guide

29 Contract Terms Data Input File Use the Contract Terms Data Input file (terms.xls) to add, update, or delete the terms for a contract. Consider the following points for the data in the contract terms data input file: v You can add only those terms to the contract that are already created in the Emptoris Contract Management application. You cannot create term definitions in the application by using the Standard Loader. v The date format of each term is configured in Emptoris Contract Management. In addition to data type constraints, term definitions can also have entry type constraints. If a term definition has an entry type of List of Values, ensure that the values that you specify in the contract data input file match the existing values. v Term values are case-sensitive. To view a sample term data input file, see the terms.xls file that is provided with the blu.tar file. Note: To add the contract terms when you create the contract, use the contracts.xls file. Fields in the Term data file The following table lists the fields for the term data input file. Table 8. Term Data Field No. Field Name Max. Length Required Comments 1 Action 1 Y Valid action types include A (Add), U (Update), and D (Delete). 2 Token 300 N For general use. Enter additional information for the term. 3 Contract Number 10 Y Identifies the Contract Number of the contract for the term. 4 Term Name 240 Y Name of the term. 5 Term Value Y The value of the term. The term value can be of type string, date, numeric, currency, or percent. The maximum length for the term value depends on the data type for the term. Product Data Input File Use the Product Data Input file (products.xls) to create, update, and delete the products in Emptoris Contract Management. Consider the following points before you create, update, or delete a product. v You can delete a product only if the following conditions are satisfied. The product is not used in any price list. The product is not referenced by another product as a replacement product. v If the External ID and External Source are provided, the combination must be unique. Chapter 4. Standard Loader 21

30 v If the externalinfo.editable flag is set to false, you cannot edit the external information for the product. To view a sample product data input file, see the products.xls file that is provided with the blu.tar file. Fields in the Product data file The following table lists the fields for the product data input file. Table 9. Product Data Field No. Field Name Max. Length Required Comments 1 Action 1 Y Valid action types include C (Create), U (Update), and D (Delete). 2 Product Number 100 Y The number of the product. 3 Product Name 300 Y The name for the product. 4 Product Type 4 Y The type of product. Valid values are Buy and Sell. 5 Notes CLOB N Information about the product. This information can be accessed from the UI. 6 External ID 100 N The ID of the product as defined in a system outside Emptoris Contract Management. 7 Version 10 N The version of the product. 8 New Product Name 300 N Use this field to update the name of a product. It is the new product name. 9 New Product Number 10 New Product Version Note: The Product Name field is used to specify the current name of the product when you update a product, or the name of the product when you create a product. 100 N Use this field to update the number for a product. It is the new product number. Note: The Product Number field is used to specify the current number of the product as it exists in the Emptoris Contract Management database. 10 N Use this field to update the version for a product. It is the new product version. Note: The Version field is used to specify the current version of the product. 22 IBM Emptoris Contract Management: Bulk Load Utilities Guide

31 Table 9. Product Data (continued) Field No. Field Name Max. Length Required Comments 11 External Source 150 N The information for the product as defined in a system outside Emptoris Contract Management. 12 Product Class 50 N The product class. 13 Product Subclass 50 N The product subclass. 14 Product Family 50 N The product family. 15 From Date Date N The date from which this product can be used. 16 To Date Date N The date up to which the product can be used. 17 Term Quantity N to The term quantity. 18 Term Unit 10 N The term unit. 19 Entitlement Term Value 20 Entitlement Term Unit 21 Create Renewal Terms 22 Replacement Product N to Can be Day, Month, or Year. The entitlement quantity. 10 N The entitlement unit. 1 N Determines whether the product can be renewed. The accepted values are Y (Yes) or N (No). 32 N The UUID for the replacement product. Custom Property Data Input File Use the Custom Property Data Input file (customproperties.xls) to update or delete the values of custom properties that are associated with Contracts, External Organizations, or Products. To view a sample custom property data input file, see the customproperties.xls file that is provided with the blu.tar file. Fields in the Custom Property data file The following table lists the fields for the custom property data input file. Table 10. Custom Property Data Field No. Field Name Max. Length Required Comments 1 Action 1 Y Valid action types include U (Update), and D (Delete). 2 Token 300 N For general use. Enter additional information for the custom property. Chapter 4. Standard Loader 23

32 Table 10. Custom Property Data (continued) Field No. Field Name Max. Length Required Comments 3 Object Type 32 Y Identifies the object for which the custom property is defined. Valid values are Organization, Product, and Contract. 4 Object External Id 5 Custom Property Name 6 Custom Property Value 300 N External ID of the object for which the custom property value is updated or deleted. v For a contract, provide the Contract Number. v For a product, provide the Product Number. v For an external organization, provide the External Organization ID. 30 Y Name of the custom property. Y The value of the custom property. The custom property value can be of type string, date, numeric, currency, or percent. The maximum length for the custom property value depends on the data type for the custom property. Loading data with the Standard Loader When you run the standard loader and load data, you can view and correct data errors, if any, and reload data as required. You can load data by using the Standard Loader in the following ways: v By creating a Job from the UI. v By using the Command Line Interface. Creating a Job from the UI You can use the Emptoris Contract Management User Interface to create a Standard Loader job. About this task For a contract job, if you cancel the job after the job starts, the job stops only after the current row is processed completely. Changes in the application due to the rows that are processed before the job is canceled are not rolled back. Procedure To create a Standard Loader job, complete the following steps: 1. On the Administration tab, go to Application and click Job List. 2. Click New. 3. In the Create Job window, select the Job Type. 24 IBM Emptoris Contract Management: Bulk Load Utilities Guide

33 4. Set the Priority and the Schedule Time. To run a job immediately, leave the Schedule Time field blank. 5. Attach the input data files and click OK. Creating a Job from the CLI You can use the Emptoris Contract Management Command Line Interface to create a Standard Loader job. Procedure To create a Standard Loader job from the command-line interface, complete the following tasks: 1. Set up the system environment for the Standard Loader. For more information, see Setting Up System Environment For Standard Loader. 2. Install the JRE (Java Runtime Environment) certificate. For more information, see Installing the JRE Certificate on page Modify the import job configuration parameters in the ecm.properties file. For more information, see Modification of Import Job Configuration Parameters on page Run the Standard Loader. For more information, see Running the Standard Loader on page 27. Setting Up System Environment For Standard Loader The Standard Loader is an HTTP and Enterprise Java Beans-based utility that you can use to load contracts and other contract data into Emptoris Contract Management, in bulk quantities. About this task Consider the following points before you set up the standard loader. v The Standard Loader is supported on both the Windows and UNIX environment. v Input files in Excel format are supported on both Windows and UNIX. v The configuration of the Standard Loader must be set up to use the HTTP port of the Emptoris Contract Management application server. The Standard Loader is also supports HTTPS. Procedure To set up the required system environment for the Standard Loader, complete the following steps: 1. Ensure that the workstation on which you intend to run the Standard Loader is Java enabled, with a minimum of JDK 5.0 installed and configured. Note: You can download the Java software from technetwork/java/index.html, if it is not already installed. 2. Install JDK 5.0 or earlier in the root directory. For example, C://JDK 5.0/. 3. Set the JAVA_HOME path to the Java installation directory. 4. Ensure that JAVA_HOME is added to the list of system environment variables. 5. Extract the blu.tar file to any folder in your system. The blu.tar file contains the following resources: v The Java archive that has the BLU client - blu/lib/upload.jar - Chapter 4. Standard Loader 25

34 v BLU client batch file on Windows and BLU client shell script on UNIX - blu/script/upload.bat v v Sample input data files - blu/samples/ Examples of attachments - blu/samples/attach/ Installing the JRE Certificate If the Emptoris Contract Management application has a valid SSL certificate, you must install the JRE certificate before you run the upload.bat command. Procedure To install the JRE certificate, complete the following steps: 1. Log in to the Emptoris Contract Management application from the Internet Explorer browser. 2. In the Internet Explorer, go to View > Security Report to view the security report for the application website. 3. Click View Certificates. 4. In the Certificates window, go to the General tab and click Install Certificate. 5. In the Certificate Import Wizard, follow the steps to import the certificate. Select the Automatically select the certificate store based on the type of certificate option for the Certificate Store. 6. In the Internet Explorer, go to Tools > Internet Options. 7. In the Internet Options window, go to the Content tab and click Certificates. 8. In the Certificates window, go to the Other People tab, select *.emptoris.com and click Export. 9. In the Certificate Export Wizard, follow the steps to export the certificate by selecting the following options: a. Select DER encoded binary X.509 (.CER) as the export file format. b. Enter the file name and select the location to save the certificate file. 10. Run the keytool -import command to import the certificate file into the cacerts keystore. You must run the command from the bin directory for the JRE. For example, if the certificate file is in the C:\ directory and the path for the JRE is C:\Program Files (x86)\java\jre7, then go to the C:\Program Files (x86)\java\jre7\bin directory and run the following command. keytool -import -alias emptoris -keystore..\lib\security\cacerts -file C:\emptoris.cer 11. Follow the steps to add the certificate to the keystore. 12. In the Environment Variables, add the JRE path to the JAVA_HOME System Environment Variable and add JAVA_HOME to the PATH System Environment Variable. Note: To access the Environment Variables, in Windows Explorer right-click My Computer and click Properties. In the Control Panel Home window, click Advanced System Settings. In the System Properties window, go to the Advanced tab and click Environment Variables. Modification of Import Job Configuration Parameters Scheduling and execution of an Import Job depends on the quartz configuration parameters that are listed in the ecm.properties file. 26 IBM Emptoris Contract Management: Bulk Load Utilities Guide

35 Process Schedules (Contract Activation, Expiration, Termination, and so on) are managed on the DEFAULT queue. One of the Process Schedules is the Job Cleanup Task that periodically purges expired jobs from the job/job_attachment tables. You can modify the values of the job import configuration parameters as required. Note: If more than one application server is connected to a database schema, the DMS directory must be shared. Otherwise, attachments that are created by one application server are not accessible with other application servers. This applies to contract attachments and job attachments. Job import configuration parameters Table 11. Job import configuration parameters Parameter Default Value Description job.groups.supported DEFAULT When you are installing a multiple application server environment, the Import or IOReporting queues might be moved off the primary application server. In such cases, the job.groups.supported resource can be changed to reflect only those queues that can be managed on that particular server. However, the or ASync queues cannot be moved off from the primary server. Other values supported are Import, , ASync, Workflow, and IOReporting job.default.max_threads 7 For each supported queue, you can configure the number of concurrent threads job.xxx.max_threads. job.import.max_threads 1 job. .max_threads 3 job.async.max_threads 2 job.workflow.max_threads 2 job.ioreporting.max_ threads 1 job.expiration.days 7 Indicates how many days old a completed job must be before it can be purged. job.failedserver.seconds 240 The queue management system frequently assesses the state of all application server instances. If a server does not respond in the specified time, then it is assumed that the application server has stopped responding. Running the Standard Loader You can load the data into Emptoris Contract Management by using the command line feature. Chapter 4. Standard Loader 27

36 Before you begin Before you import the contract data from the contracts.xls file, make sure that the referenced data exists in the application. For example, the Contract Classes, Contract Templates, and Term Definitions must be present in the application. About this task The <importtype> and the corresponding <document> are described in the following table. Table 12. Import Type and corresponding document. Import Type contract contractparty contractline contractterm customproperty product Document contracts.xls parties.xls lines.xls terms.xls customproperties.xls products.xls You can add the following optional parameters to the upload command for the Standard Loader. Table 13. Optional parameters for the Standard Loader. Parameter Description -l language (language locale) Use when language is different from user's language. For example, en_us. -i items (lines) filename Use to upload lines along with the contract. -f date format (mm/dd/yyyy or dd/mm/yyyy) -s schedule (time in yyyy-mm-dd hh:mm:ss format) Use when date format is different from the user's default date format. Default value is immediate. -p job priority (number) A number between Default value is 5. -a attachments - pipe ( ) Delimited list of attachment files and directories. -d deep traversal (true or false) Default value is true. -z gzip (true or false) Default value is true. -m parties filename Use to upload parties along with the contract. Procedure To import and load each data input file into Emptoris Contract Management, complete the following steps: 1. From the command line, locate the directory <blu directory>\scripts. 2. You must provide a minimum of five command-line arguments in the following format: upload.bat HttpListener <username> <password> <importtype> <document> 28 IBM Emptoris Contract Management: Bulk Load Utilities Guide

37 Note: The user that is specified must belong to the internal party on the contract and must have the permissions to create or edit contracts. Example The following examples display how to upload different input files by using different command-line arguments and optional parameters. The examples assume that the blu.tar file is extracted in the C drive at the root level, and that the user name and the password are "admin". Table 14. Examples for uploading input files by using different command-line arguments and optional parameters. Job Importing contract data along with attachments. Importing contract data along with parties data. Importing contract data along with lines data. Importing custom property data. Scheduling an import job to run in future by using the -s <argument>. Command C:/blu/scripts/upload /dicarta/servlet/httplistener admin admin contract..\samples\contracts.xls -a..\samples\attach C:/blu/scripts/upload <hostname:port> /dicarta/servlet/httplistener admin admin contract..\samples\contracts.xls -m..\samples\parties.xls C:/blu/scripts/upload servlet/httplistener admin admin contract..\samples\contracts.xls -i..\samples\lines.xls C:/blu/scripts/upload servlet/httplistener admin admin customproperty..\samples\customproperties.xls C:/blu/scripts/upload servlet/httplistener admin admin contract..\samples\contracts.xls -s " :00:00" Reviewing the Import Job Results and Error Logs After you upload contract data, you can see the import job results. The import job results and job details are displayed on the Administration UI of the application. The Jobs List section of the Administration displays a list of import jobs and their status. Before you begin You must have the required permissions to see the Jobs List and Job Control sections in Administration. Procedure 1. On the Administration tab, go to Application and click Job List. 2. Search for the job. 3. Click the Name of the job to see the job details. Results The following actions occur when a Standard Loader job is run. v For a contracts job, the contracts that are successfully uploaded are stored in the Emptoris Contract Management Repository. Chapter 4. Standard Loader 29

38 Tip: If a contract template that you specified supplies folder names, you can go to these folders in the Emptoris Contract Management Repository to locate the contracts that are loaded with that template. v For a Create Contracts job, a Results.txt file is created which contains all error messages. It also displays the contract numbers for the contracts that were created successfully. v For all jobs except the Create Contracts job, a Retry.xls file is created which contains only those rows that failed to load. You can use this file to upload the failed rows after you make the required corrections to the data. For more information on viewing job status and details, rescheduling jobs, or canceling jobs, see the IBM Emptoris Contract Management System Administration Guide. Status of Contracts uploaded by using the Standard Loader The status of a contract that is loaded by using the Standard Loader depends on whether an execution date applies. Consider the following points for the contract status: v If an execution date is specified and effective start date falls after current date, the status of the contract is set to Executed. v If the execution date is not provided (is blank), the status of the contract is set to Draft. v For an Executed contract, if the effective start date falls on or before the current date, the status is set to Active. v For an Executed contract, if the effective end date is specified, and this date falls on or before the current date, the status is set to Expired. v If the contract template has approvals defined or if the approval rules are set, the contract is loaded in Draft status and the user is notified that approvals are required to present or execute the contract. If the contract execution date is specified, an error message is generated and the contract is loaded in Draft status. Change in Status for an Executed Contract After an Executed contract is loaded, its status might change according to the effective start date and effective end date that is supplied in the input file and the frequency of the Contract Status Update process. The Contract Status Update process is scheduled by using the Process Schedules feature in Emptoris Contract Management Administration. For more information, see the IBM Emptoris Contract Management System Administration Guide. After the Process Schedules are run, the status of a loaded contract can have the following possible values: v Active: The agreement is executed and now in effect. v Draft: The agreement is yet to be executed. v Executed: The agreement is executed. v Expired: The agreement is executed and now expired. Note: For details on these and other status values, see the IBM Emptoris Contract Management User Guide. 30 IBM Emptoris Contract Management: Bulk Load Utilities Guide

39 Dealing with Lines that Failed to Upload The failed lines are saved in an Excel file that is available on the Contract Editor Lines: Instances tab after the line instances. You can download this file, view the errors, edit the lines, and upload the corrected lines by using this file. v The Excel file contains only the lines that failed to upload. v An Errors column is added at the end and contains information about the error for the line. The tooltip for the Excel file displays the user name and the file creation date. Lines that are saved to the line upload error file Lines are saved to the line upload error file in the following instances: v Validation errors occur for fields in the lines. v The field definitions do not match the existing fields. In this case, all the lines for the line definition are saved in the error file. However, the error is only displayed in the first row. Lines that are not saved to the line upload error file Lines are not saved to the line upload error file in the following instances: v The line definition (Line Type Name) specified in the upload file is not found in the lines definitions that are added to the contract. v The three mandatory columns for a line (Contract Row Number or Contract Number, Action, Line Type Name) are not included. v An empty value is provided in Action or Line type Name columns for any line. v An unexpected error occurs when the uploaded lines are being processed. Editing, Saving and Uploading the Line Upload Error File The failed lines are saved in an Excel file that is available on the Contract Editor Lines: Instances tab after the line instances. Procedure To edit, save, and upload the line upload error file, complete the following steps: 1. Click the line upload error file link. 2. In the File Download window, click Save. 3. In the Save As window, browse and select the location to save the Excel file. 4. Click Save. By default, the file is saved as <contract_number>-line upload error file.xls. 5. Make the appropriate corrections to the lines and save the file. Note: You do not need to delete the Errors column. 6. Upload the file to add the lines to the contract. Note: If all lines are uploaded successfully, the line upload error file is no longer available for downloading. You can also delete the line upload error file link from the Contract Editor Lines: Instances tab. Chapter 4. Standard Loader 31

40 32 IBM Emptoris Contract Management: Bulk Load Utilities Guide

41 Chapter 5. Fast Loader The Fast Loader is a SQL-based bulk load utility that enables the user to load high volumes of data into Emptoris Contract Management on a recurring and non-recurring basis. Data loading is exponentially faster than with the Standard Loader. The Fast Loader uses staging tables to load data to the application objects, and database stored procedures to drive the SQL load. The stored procedures contain the business validation and process control logic to ensure the integrity of the data that is loaded into the Emptoris Contract Management Repository. Overview of the Fast Loader Data Loading Process The following illustration highlights the key components and data loading process of the Fast Loader. Fast Loader Components The function of the Fast Loader is based on two main components - Staging tables and stored procedures. Client programs load the data into the staging tables and start the stored procedures. The stored procedures insert, update, or delete the data from the Copyright IBM Corp. 2012,