ZL Unified Archive High Performance API Kit

Transcription

1 2015 ZL Unified Archive High Performance API Kit ZLUA Copyright 2016 ZL Technologies Inc. January 2016

2 Copyright 2016 ZL Technologies, Inc. All rights reserved. ZL Technologies, Inc. ( ZLTI, formerly known as ZipLip ) and its licensors retain all ownership rights to the software programs offered by ZLTI (referred to herein as Software ) and related documentation, (together, the Products ). Use of the Software and related documentation is governed by the license agreement accompanying the Software and applicable copyright law. Your right to copy the Products is limited by copyright law and the license agreement. Making unauthorized copies, adaptations, or compilation works is prohibited. ZLTI may revise this documentation occasionally without notice. THIS DOCUMENTATION IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL ZLTI BE LIABLE FOR INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY KIND ARISING FROM ANY ERROR IN THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION ANY LOSS OR INTERRUPTION OF BUSINESS, REVENUE, USE, OR DATA. Other product and company names appearing in ZLTI products and materials are used for identification purposes only and may be trademarks or registered trademarks of their respective companies. Third party trademarks used in any ZLTI products and materials are the exclusive property of their respective owners.

3 Table of Contents Table of Contents About this guide... 7 Audience... 7 What You Need to Know... 7 Conventions Used Getting Started With ZL UA API Kit Introduction API Kit Design Goals API Architecture Security Considerations Functionality Overview When to Use API Supported Version and Development Development Platforms What s New in Version 2.0 API Kit Generally Available Enhancements Other Changes Earlier Versions Quick Start Prerequisites Step One: Setup Authorization Create OAuth Consumer Create OAuth Client Certificate and Password Step Two: Connecting to ZL Servers Walk through a Code Sample Samples in C# List Users Create Case Data Source Samples in JAVA Uploading a File Uploading Mail Searching for a Message Searching Storage Searching Storage... 33

4 Table of Contents 3 Using ZL API Kit Resources Using the API Kit with Java and.net Server and Account Requirements Server Configuration Security Roles and Privileges Role Privilege Initialization IConnectorInfo And Now Some Services Listing Archive Departments How to Use the ZL API Kit Object Schema ZL Services Core Packages Department Administration Getting a Department Finding a Department Creating a Department Updating a Department Deleting a Department Mail Server Administration Getting a Mail Server Finding a Mail Server Creating a Mail Server User Administration Getting an Archive User Finding Archive Users by Department Creating a User Account Checking if a User is a Group Getting All Group Members Adding a Member to the Group Removing a Member from the Group Updating a User s Profile Terminating a User Account Restoring a Terminated User Account Deleting an Archive User Account Creating a Child Department

5 Table of Contents Moving User to a New Department Managing User Aliases Managing Reviewers on a Department Role Administration Listing all System Roles Listing all Custom Roles Listing System Roles Assigned to a User Making a Role to Assign or Revoke Archived Folder Navigation on a Specific User Archived Mail Navigation through a User s Folder Searching for Mails Creating a Search Condition Navigating through Mails from the Search Result Message Handling Downloading Message Uploading Message File Archiving & Storage Related API Object Schema ZLServices Files and Storage Packages Project Administration Getting a Project Finding a Project Creating a Project Updating a File Project Creating a Sharepoint Project Updating a Sharepoint Project Creating a Documentum Project Updating a Documentum Project Navigating through a Project s File Folders Navigating through a Project Folder s Archived Files Searching for Files Obtaining a Search Store Issuing a Search Query Creating a Search Condition Navigating through Files from the Search Result File handling Downloading a File Uploading a File

6 Table of Contents 6 Case Management Related API ZLServices Case Management Packages Case Creation Creating a case Case Administration Getting a Case Finding Cases with Name Pattern Finding Cases Belonging to a Particular Domain Revoking a Specific User s Access to All the Cases Custodian Administration Getting a Custodian Adding a Custodian Updating a Custodian Removing a Custodian Managing Aliases of a Custodian Case Reviewer Administration Getting a Reviewer Adding a Reviewer Removing a Reviewer Case Tag Administration Getting Root Level Tags Adding Tags Updating Tags Removing Case Tags Getting Child Tags Case Data Source Administration Creating Case Data Source Scheduling Case Data Source Runs Getting Case Data Sources Getting Run Schedules of Case Data Sources Navigating through a Case s Case Folders Searching for Case Items Navigating through Case Items from the Search Result Generating Case Reports (Excel/ZAR) Exceptions Logging API Kit Reference API Reference

7 Table of Contents 9.2 Top Level Packages: ZLServices ZLServices Core ZLServices MTA ZLServices Search ZLServices Mail ZLServices Storage ZLServices Tracker ZLServices Case Management Samples Package

8 Preface Preface About this guide The ZL Unified Archive (UA) module provides organizations with the ability to archive project files with enterprise-level capabilities. Audience This document is for system administrators in charge of setting up the ZL UA module. What You Need to Know Before starting this manual, you need to read the ZLUA 8.0 Technote System Requirements for hardware and software requirements. Conventions Used Text in Courier indicates: Filenames, commands, and programs Text that you enter Text that the system displays Words printed in italics are generic terms representing names to be devised by you. Square brackets [ ] mean that the material inside of them is optional. Braces { mean that you must choose from the options listed inside of them. If there is only one option in the braces, the braces mean the option can be repeated. If a command line does not fit across the page, a backward slash (\) appears at the end of the line, and the command continues on the next line.

9 Getting Started With ZL UA API Kit 1 Getting Started With ZL UA API Kit This document highlights the major design changes in the ediscovery module for ZL UA Introduction ZL provides programmatic access to your organization's information using simple, powerful, and secure application programming interfaces. To use this document, you should have basic familiarity with software development and the ZL UA user interface. 1.2 API Kit Design Goals The purpose of the ZL API kit is to provide a comprehensive and thorough programmatic development kit to make ZL server services available in a high performance and high scalability fashion. The main design goals for the API kit: 1. The clients can be on the LAN or anywhere on the Internet. 2. In the cases where communication should comply with enterprise firewall needs, it can be limited to HTTP or HTTPS. API client to ZL server communication can also happen on the TCP port 9971 in the cases where this port can be opened up. 3. Client Server communication leverages ZL data transfer protocol, which is faster than the traditional web services API kit. The API kit is distributed only in the Java and C# (.Net) programming languages. Clients can only be written in one of these two programming languages and on any respective supporting operating systems. 4. The toolkit supports the bidirectional transfer of large amounts of data, including uploading content to the ZL server as well as downloading data. 5. The toolkit provides a comprehensive and programmatic way to access various services/modules provided by the ZL server, such as records management, legal hold management, case management, user and department management, content uploads/ downloads, searches etc. 1.3 API Architecture The ZL Big Data API kit is built using ZL data transfer protocol/framework. This protocol is capable of streaming data both ways and hence is used to upload content from client as well as download content from the ZL server. The communication transport layer for these API calls can either be HTTP/HTTPS or TCP. If the API based client and ZL server are communicating over HTTP/HTTPS it doesn t require any special firewall requirements. If the communication is desired on TCP, a special port 9971 on which ZL server listens for client requests has to be opened up on the firewall. As the API is based on ZL data transfer protocol, the only client libraries distributed are in Java and C#. Hence the clients can only be in one of these two programming languages on any operating system. The figure below shows the general client framework. Note that the API-based clients can be remote and can reside in the same network (exist within the LAN of the servers) or an external network in which case the communication happens over the Internet. 8

10 Getting Started With ZL UA API Kit Figure 1 ZL API Kit general client framewaorks 1.4 Security Considerations 1. The general ZL server API client authentication is based on the open standard for authorization, OAUTH In this authentication, a client accessor certificate along with its password is used to authenticate the sessions. More information about this accessor certificate and how to generate this on the ZL server is explained in the next chapter. Certificate user s roles and privileges are set on the ZL server to control access and authorization to various API based functionality. 3. The API kits enable developers to create session against multiple ZL deployments. This is particularly useful in the case where many ZL deployments need to be managed with a single API client. The only requirement to achieve this is to provide the accessor certificate and respective password combinations corresponding to each of the ZL deployments. 4. In the case of multi-tenant environments, the accessor certificate is generated for a particular tenant of interest and hence this security model will restrict the session to a particular tenant resources. It is not possible to access the resources of all the tenants with a single session. More information on how this is done is explained in the next chapter. 1.5 Functionality Overview The ZL Big Data API Kit is designed to manage ZL Unified Archive from the administration point of view. The main services/features provided by the API kit include but are not limited to: (a) Manage Departments, Mail servers and policies. (b) Manage Users, their roles and privileges. (c) Comprehensive access to Mail archive. This includes accessing, downloading, uploading, searching of meta data and data of all types of content including all mail, Bloomberg, IM, Social Media, etc., that are archived by ZL server. 9

11 Getting Started With ZL UA API Kit (d) Manage and access File Archives. This includes accessing, downloading, uploading and searching of metadata and data of all types of files that are archived from File servers, SharePoint servers and other content repositories. (e) Create and manage cases. (f) Manage Legal Holds and Retention Changes. (g) Records Management API s. (h) Custom integration with third party tools. 1.6 When to Use API ZL UA provides powerful functionalities. In addition, ZL provides the ability to customize the prebuilt modules to fit your organization. However, your organization may have complex business processes that are unsupported by the existing functionality. When this is the case, ZL API Kit includes a number of ways for advanced administrators and developers to implement custom functionality. 1.7 Supported Version and Development The ZL UA version and above is the minimum version requirement for using the API Kit platform. To develop client applications, it is strongly recommended that you use Developer Sandbox, which is an exact replica of your ZL UA, including all customization and data. For licensing details, please contact your account representative. 1.8 Development Platforms The ZL API works with Java and C#. In this document examples are provided in Java. The Java examples are based on JDK 7 (Java Platform Standard Edition Development Kit 7). 1.9 What s New in Version 2.0 API Kit Generally Available Enhancements All objects are new Other Changes N/A 1.10 Earlier Versions N/A 10

12 Quick Start 2 Quick Start The purpose of the ZL API kit is to provide a comprehensive and thorough programmatic development kit to make ZL server services available in a high performance and high scalability fashion. The ZLServices.zip constitute the SDK which can be installed on a client machine. This does not need to be installed on ZL Server. The ZLServices.zip contains two directories: java and dotnet. The java directory contains ZLServices-8.0.jar and zlthin-common-8.0.jar for use as library files for customer application development. Also provided are Javadocs for the ZLServices and samples, and sources to the samples. The dotnet directory contains a ZLServicesSamples zip file containing ZLServices.dll and zlthin-common.dll for use as library files for customer application development. Also provided is a sample project and sources to the samples that are ported from the Java samples. The dotnet version is similar to the Java version, so the Javadocs can be used with some caveats to describe the dotnet classes and methods. Any differences should be visible when comparing the samples between the Java and dotnet versions. 2.1 Prerequisites The Java version of the API kit is supported on Windows 2008, Windows 2003, Solaris, and Linux platforms. The API consists of the following sets of JAR files located in the $ZLServices/bin and the $ZLServices/lib directories, where $ZLServices is the directory in which you have installed the ZL Services API kit: bin/zlservices-8.0.jar Contains ZL API Kit Code lib/zlthin-common-8.0.jar - Contains the network and proprietary data transfer protocol The pre-requisites to access the functionality of the API Kit are: JDK 1.7 or above or JRE 1.6 or above To use the API Kit, make sure these JAR files are in the classpath. You are now ready to use the API kit. In DotNet version lib folder contains libraries for compiling the samples, or any other project the end-user developer would create. This includes the ZLServices.dll and zlthin-common.dll, along with the debug symbols for problem diagnosis. 11

13 Quick Start Figure 2 DotNet version lib folder The bin\release directory is the samples in compiled form, containing all files necessary to run the samples. The samples require a certificate for connection. While this folder contains the libraries as well, this is not the SDK and can be rebuilt by the end-user developer. Figure 3..\bin\release directory 2.2 Step One: Setup Authorization Account Requirements & Security: 1. Create OAuthConsumer 2. Generate OAuth Client certificate with password The API kit needs a certificate file and an associated password to talk to the ZL server. This certificate file needs to be generated against that ZL server, for a particular OAuth Consumer (key) the API is trying to communicate with. The certificate file can be generated by running the nextpage tool OAuthClientAccessor.jsp on the ZL server. This generates: [1] Password that needs to be used with the certificate [2] Content to create the actual certificate itself. The certificate file is generated with a particular user context and as long as a particular certificate is used, that specific user associated with that certificate will serve as the logged-in user for the API call. Hence, the scope and privileges associated with using the API kit is limited by the roles 12

14 Quick Start and privileges associated with that user. Each API call is verified for different set of privileges on the server. Therefore it is necessary to give the appropriate roles and privileges to the user who will be using the API kit. ZL recommends you assign a special account for the API user and give that user appropriate roles and privileges from the ZL Unified Archive Web interface. In addition to the certificate, the password used to generate the certificate is also needed for the API kit to authenticate to the server Create OAuth Consumer OAuth Consumer can be generated by running the nextpage tool OAuthConsumer.jsp on the ZL server. D:\ZipLip\zlserver>nextpage /app/util/oauthconsumer.jsp key=zlclientservices <html> <body> <H1>Done </H1> <p> Done <br>created consumerconsumer zlclientservices secret=el5lwun0d3b2glrqhszz0lpi5gr1ya5jb </body></html> D:\ZipLip\zlserver> Figure 4 OAuth Consumer Creation 13

15 Quick Start Create OAuth Client Certificate and Password OAuth Consumer can be generated by running the nextpage tool OAuthClientAccessor.jsp on the ZL server. D:\ZipLip\zlserver>nextpage /app/util/oauthclientaccessor.jsp key=zlclientservices pwd=password <br>success generating ClientAccesor Password:PTG3CDAD2PKVWQBTVLD4ZEKJRUIFC0JLB Cut and paste to a file including BEGIN and END ---BEGIN ZLOAUTH---- LgmtpRnml4Vf/IoGXZuGkeTQqHp4XkUO2mwtBErNcTBS7VHhb/+5CSZwXsGjXvv/O82Dlk0+t UODHIQIXdk8TP+8jhVN0OUkwkCU7LytPzqWpMfegmCDjdzF1pURbfswp3KJ81WkQDpPVaXdbO x9vekxwai7e/vfblbwy8maounybzkvcsuinu1lhxeum/9s ---END ZLOAUTH---- <html> <body> <H1>Done </H1> <p> Done <br>verifysuccessfully loaded </body></html> D:\ZipLip\zlserver> 14

16 Quick Start Figure 5 OAuth Client Accessor Certificate and Password creation Create a new file say apikitadmin.cert and paste above content. For example, the file may look like the following figure in notepad editor. Figure 6 OAuth Client Accessor Certificate Sample 2.3 Step Two: Connecting to ZL Servers The following are required to connect to a ZL server: 1. The URL of the ZL server. ZL supports two ways of connections from the API kit. They are the TCP on 9971 and HTTP on For example, if the ZL server to which API needs to establish a connection is machine1, the URL will be of the form or tcp://machine1. 2. Certificate file (its location with full path) and password. 15

17 Quick Start 2.4 Walk through a Code Sample Samples in C# List Users using System; using System.IO; using ZLCS.wsi.services; using ZLCS.wsi.util; using ZLCS.com.ziplip.zlcp.util; using ZLServices.com.zlti.zlservices.core; using ZLServices.com.zlti.zlsImpl.core; namespace samples.com.zlti.zlservices {public class ListUsers { public static void main(string[] ast){ if(ast.length < 4){ Console.WriteLine("Usage -- prgname url certfile certpwd alias"); return; try { ZLClientServicesHome.init(new DirectoryInfo("log")); ZLClientServicesHome.initThread(); String sturl = ast[0]; String stcertfile = ast[1]; String stcertpwd = ast[2]; String stalias = ast[3]; 16

18 Quick Start IConnectorInfo connectorinfo = ZLClientServicesHome.getConnectorInfo(stUrl, stcertfile, stcertpwd); IArchiveUserInfo archuserinfo = CoreHome.getUserUsingAlias(stAlias, connectorinfo); Console.WriteLine("ArchiveUserInfo = [" + ((ZArchiveUserInfo)archUserInfo).getPersistent()); catch (Exception e){ Console.WriteLine(e.StackTrace); finally { ZLClientServicesHome.releaseAll(); Console.WriteLine("Done Setting up Client!!"); // end namespace Create Case Data Source using System; using System.IO; using ZLCS.wsi.services; using ZLCS.wsi.util; using ZLCS.com.ziplip.zlcp.util; using ZLServices.com.zlti.zlservices.core; using ZLServices.com.zlti.zlservices.core.search; using ZLServices.com.zlti.zlservices.app.caseMgmt; using ZLServices.com.zlti.zlservices.app.mail; using ZLServices.com.zlti.zlsImpl.core.search; namespace samples.com.zlti.zlservices { 17

19 Quick Start public class CreateCaseDataSource { public static void main(string[] ast) { if (ast.length < 4) { Console.WriteLine("Usage -- prgname url certfile certpwd casename"); return; try { ZLClientServicesHome.init(new DirectoryInfo("log")); ZLClientServicesHome.initThread(); IAppCallback appcb = ThreadContext.getApp(); int nparam = 0; String sturl = ast[nparam++]; String stcertfile = ast[nparam++]; String stcertpwd = ast[nparam++]; String stcasename = ast[nparam++]; String stprefix = "Sample API"; IConnectorInfo connectorinfo = ZLClientServicesHome.getConnectorInfo(stUrl, stcertfile, stcertpwd); ICaseInfo[] acaseinfo = CaseHome.getAllCaseInfoUsingNameSearch(stCaseName, connectorinfo); if(acaseinfo!= null && acaseinfo.length > 0){ ISearchQuery query = MessageSearchHome.createSearchQuery(); ISearchCondition condbody1 = query.makeanyphrasecondition(messagesearchfields.field_body, "test"); ISearchCondition condbody2 = query.makeexactphrasecondition(messagesearchfields.field_attachment, "any of"); 18

20 Quick Start ISearchCondition condbody = query.combine(zsearchquery.comb_opid_or, new ISearchCondition[]{condBody1,condBody2); ISearchCondition condsize = query.makerangecondition(messagesearchfields.field_message_size, 1024, 1024 * 1024); ISearchCondition conddate = query.makerangecondition(messagesearchfields.field_msg_date, new DateTime(DateTime.UtcNow.Ticks - 365L * 86400L * 1000L * 10000L), new DateTime()); ISearchCondition condcombined = query.combine(zsearchquery.comb_opid_and, new ISearchCondition[]{condBody,condSize,condDate); query.close(condcombined); bool fapplylegalhold = true; ISearchStore[] astores = MessageSearchHome.getAllSearchStores(true,true,connectorInfo); foreach(isearchstore store in astores){ appcb.logln(log.log_general,"doing search on store = " + store.getentitystorename()); String stname = stprefix + "_" + store.getentitystorename(); ICaseDataSource datasrc = acaseinfo[0].createcasedatasource(null, stname, store, query, null, fapplylegalhold); fapplylegalhold =!fapplylegalhold; if(datasrc!= null){ Console.WriteLine("Created case data source " + datasrc.getname()); datasrc.schedule(new DateTime(), 86400L * 1000L, new DateTime(DateTime.UtcNow.Ticks + 365L * 86400L * 1000L * 10000L), 100); catch (Exception e) { 19

21 Quick Start Console.WriteLine(e.StackTrace); Console.WriteLine("Done Setting up Client!!"); // end namespace Samples in JAVA Uploading a File package samples.com.zlti.zlservices; import java.io.file; import java.io.fileinputstream; import java.io.inputstream; import java.util.date; import wsi.io.transactionoutputstream; import com.ziplip.zlcp.util.iconnectorinfo; import com.zlti.zlsimpl.app.storage.zfileupload; import com.zlti.zlservices.app.mail.messagetype; import com.zlti.zlservices.app.storage.ifileupload; import com.zlti.zlservices.app.storage.istorageprojectinfo; import com.zlti.zlservices.app.storage.storagehome; import com.zlti.zlservices.core.zlclientserviceshome; public class FileUpload { public static void main(string[] ast) { if (ast.length < 5) { System.out.println("Usage -- java prgname url certfile certpwd project file"); 20

22 Quick Start return; try { ZLClientServicesHome.init(new File("log")); ZLClientServicesHome.initThread(); int nparam = 0; String sturl = ast[nparam++]; String stcertfile = ast[nparam++]; String stcertpwd = ast[nparam++]; String stproject = ast[nparam++]; String stmailfile = ast[nparam++]; File file = new File(stMailFile); String stsourceinfo = file.getname(); String stsourcemiscinfo = null; IConnectorInfo connectorinfo = ZLClientServicesHome.getConnectorInfo(stUrl, stcertfile, stcertpwd); IStorageProjectInfo projinfo = StorageHome.getProjectUsingName(stProject, connectorinfo); String strelativepath = "aa\\bb\\cc"; IFileUpload fileupload = StorageHome.uploadFile(projInfo.getProjectId(), strelativepath, file.getname(), file.getname(), "text/plain", new Date(), new Date(), MessageType.FILE_ARCHIVE, stsourceinfo, stsourcemiscinfo, connectorinfo); int idversion = 4; ((ZFileUpload)fileUpload).setVersionInfo(idVersion, "Version:4", null); 21

23 Quick Start TransactionOutputStream tos = fileupload.getuploadstream(); InputStream is = new FileInputStream(file); MailUpload.pumpIO(is, tos); tos.close(); is.close(); String strmid = fileupload.getreceivedmailid(); System.out.println("Upload File " + file.getabsolutepath() + " ReceivedMailId=" + strmid); catch (Exception e) { e.printstacktrace(); System.out.println("Done Setting up Client!!"); Uploading Mail package samples.com.zlti.zlservices; import java.io.file; import java.io.fileinputstream; import java.io.ioexception; import java.io.inputstream; import java.io.outputstream; import wsi.io.transactionoutputstream; import com.ziplip.zlcp.util.iconnectorinfo; import com.zlti.zlservices.app.mail.imessageupload; 22

24 Quick Start import com.zlti.zlservices.app.mail.messagehome; import com.zlti.zlservices.app.mail.messagehome.mailuploadconstants; import com.zlti.zlservices.app.mail.messagetype; import com.zlti.zlservices.core.zlclientserviceshome; /** * Uploads message to archive */ public class MailUpload { /** * Uploads message to archive using hard-coded parameters ast command line arguments in the following order: * url - url of ZLServer * certfile - path to the user authentication file generated by ZLServer * certpwd - password to open the user authentication file * mailfile - file containing message to archive */ public static void main(string[] ast){ if(ast.length < 4){ System.out.println("Usage -- java prgname url certfile certpwd mailfile [msgtype]"); return; try { ZLClientServicesHome.init(new File("log")); ZLClientServicesHome.initThread(); int nparam = 0; String sturl = ast[nparam++]; String stcertfile = ast[nparam++]; String stcertpwd = ast[nparam++]; 23

25 Quick Start String stmailfile = ast[nparam++]; File file = new File(stMailFile); String stsourceinfo = file.getname(); String stsourcemiscinfo = null; IConnectorInfo connectorinfo = ZLClientServicesHome.getConnectorInfo(stUrl, stcertfile, stcertpwd); IMessageUpload msgupload = MessageHome.uploadMessage(MailUploadConstants.UPLOAD_TYPE_MIME, MessageType.FACEBOOK, false, stsourceinfo, stsourcemiscinfo, connectorinfo); TransactionOutputStream tos = msgupload.getuploadstream(); InputStream is = new FileInputStream(file); pumpio(is,tos); tos.close(); is.close(); String strmid = msgupload.getreceivedmailid(); System.out.println("Upload File " + file.getabsolutepath() + " ReceivedMailId=" + strmid); catch (Exception e){ e.printstacktrace(); System.out.println("Done Setting up Client!!"); /** * Copy InputStream i to OutputStream o 24

26 Quick Start i InputStream o OutputStream number of bytes copied IOException wsi.util.miscutil#pumpio(java.io.inputstream, java.io.outputstream) */ public static int pumpio(inputstream i, OutputStream o) throws IOException { return pumpio(i, o, 1024); /** * Copy InputStream i to OutputStream o using byte[] with size ibuffsize i InputStream o OutputStream ibuffsize byte[] size number of bytes copied IOException wsi.util.miscutil#pumpio(java.io.inputstream, java.io.outputstream, int) */ public static int pumpio(inputstream i, OutputStream o, int ibuffsize) throws IOException { int sz; int total = 0; byte[] buff = new byte[ibuffsize]; while ( (sz = i.read(buff))!= -1) { o.write(buff, 0, sz); total += sz; return total; 25

27 Quick Start Searching for a Message package samples.com.zlti.zlservices; import java.io.file; import java.io.fileoutputstream; import java.io.inputstream; import java.io.outputstream; import java.util.date; import wsi.io.fileutil; import wsi.services.iappcallback; import wsi.services.threadcontext; import wsi.util.ilog; import wsi.util.miscutil; import com.ziplip.zlcp.util.iconnectorinfo; import com.zlti.zlsimpl.app.mail.zzlpmessage; import com.zlti.zlservices.app.mail.imessagesearchresultset; import com.zlti.zlservices.app.mail.izlpmessage; import com.zlti.zlservices.app.mail.messagesearchfields; import com.zlti.zlservices.app.mail.messagesearchhome; import com.zlti.zlservices.core.zlclientserviceshome; import com.zlti.zlservices.core.search.isearchcondition; import com.zlti.zlservices.core.search.isearchquery; import com.zlti.zlservices.core.search.isearchstore; /** * Exports message from archive */ 26

28 Quick Start public class MessageSearch { /** * Exports message from archive using hard-coded search parameters ast command line arguments in the following order: * url - url of ZLServer * certfile - path to the user authentication file generated by ZLServer * certpwd - password to open the user authentication file * downloaddir - directory to store search results */ public static void main(string[] ast){ if(ast.length < 4){ System.out.println("Usage : java prgname url certfile certpwd downloaddir"); return; try { ZLClientServicesHome.init(new File("log")); ZLClientServicesHome.initThread(); IAppCallback appcb = ThreadContext.getApp(); String sturl = ast[0]; String stcertfile = ast[1]; String stcertpwd = ast[2]; IConnectorInfo connectorinfo = ZLClientServicesHome.getConnectorInfo(stUrl, stcertfile, stcertpwd); ISearchQuery query = MessageSearchHome.createSearchQuery(); ISearchCondition condbody1 = query.makeanyphrasecondition(messagesearchfields.field_body, "test"); ISearchCondition condbody2 = query.makeexactphrasecondition(messagesearchfields.field_attachment, "any of"); 27

29 Quick Start ISearchCondition condbody = query.combine(isearchquery.comb_opid_or, new ISearchCondition[]{condBody1,condBody2); ISearchCondition condsize = query.makerangecondition(messagesearchfields.field_message_size, 1024, 1024 * 1024); ISearchCondition conddate = query.makerangecondition(messagesearchfields.field_msg_date, new Date(System.currentTimeMillis() - 365L*86400L*1000L), new Date()); ISearchCondition condcombined = query.combine(isearchquery.comb_opid_and, new ISearchCondition[]{condBody,condSize,condDate); query.close(condcombined); ISearchStore[] astores = MessageSearchHome.getAllSearchStores(true,true,connectorInfo); for(isearchstore store : astores){ appcb.logln(ilog.log_general,"doing search on store = " + store.getentitystorename()); IMessageSearchResultSet msgresultset = MessageSearchHome.search(store, query, null, connectorinfo); try { appcb.logln(ilog.log_general, "Resultset " + msgresultset.getcount() + ", rawquery="+msgresultset.getquery()); int i = 0; IZLPMessage msg = msgresultset.next(); while(msgresultset.hasnext()){ if(i++ < 100){ appcb.logln(ilog.log_general, "Message : [" + ((ZZLPMessage)msg).getPersistent()+"]"); else { appcb.logln(ilog.log_general, msg.getmessageid()); File filedir = new File(stFileDir); if(ast.length > 2){ //download String stfiledir = ast[3]; 28

30 Quick Start FileUtil.mkdirs(fileDir); OutputStream os = null; InputStream is = null; try { is = msg.getcontent(izlpmessage.output_mime); os = new FileOutputStream(new File(fileDir,msg.getMessageId()+".eml")); catch(throwable t1){ finally { finally { t1.printstacktrace(); MiscUtil.pumpIO(is,os); os.flush(); MiscUtil.closeQuiet(is); MiscUtil.closeQuiet(os); if(msgresultset!= null){ msgresultset.close(); catch(throwable t){ t.printstacktrace(); System.out.println("Exiting.."); Searching Storage package samples.com.zlti.zlservices; import java.io.file; 29

31 Quick Start import java.io.fileoutputstream; import java.io.inputstream; import java.io.outputstream; import java.util.date; import wsi.io.fileutil; import wsi.services.iappcallback; import wsi.services.threadcontext; import wsi.util.ilog; import wsi.util.miscutil; import com.ziplip.zlcp.util.iconnectorinfo; import com.zlti.zlsimpl.app.storage.zstorageitemversion; import com.zlti.zlservices.app.storage.istorageitemversion; import com.zlti.zlservices.app.storage.istoragesearchresultset; import com.zlti.zlservices.app.storage.storagesearchfields; import com.zlti.zlservices.app.storage.storagesearchhome; import com.zlti.zlservices.core.zlclientserviceshome; import com.zlti.zlservices.core.search.isearchcondition; import com.zlti.zlservices.core.search.isearchquery; import com.zlti.zlservices.core.search.isearchstore; public class StorageSearch { public static void main(string[] ast){ if(ast.length < 4){ System.out.println("Usage : java prgname url certfile certpwd downloaddir"); return; try { 30

32 Quick Start ZLClientServicesHome.init(new File("log")); ZLClientServicesHome.initThread(); IAppCallback appcb = ThreadContext.getApp(); String sturl = ast[0]; String stcertfile = ast[1]; String stcertpwd = ast[2]; IConnectorInfo connectorinfo = ZLClientServicesHome.getConnectorInfo(stUrl, stcertfile, stcertpwd); ISearchQuery query = StorageSearchHome.createSearchQuery(); ISearchCondition condbody = query.makeanyphrasecondition(storagesearchfields.field_name, "exec_2_ _210649"); ISearchCondition condsize = query.makerangecondition(storagesearchfields.field_size, 1, 5); ISearchCondition conddate = query.makerangecondition(storagesearchfields.field_create_date, new Date(System.currentTimeMillis() - 365L*86400L*1000L), new Date()); ISearchCondition condcombined = query.combine(isearchquery.comb_opid_and, new ISearchCondition[]{condBody,condSize,condDate); query.close(condcombined); ISearchStore[] astores = StorageSearchHome.getAllSearchStores(connectorInfo); for(isearchstore store : astores){ appcb.logln(ilog.log_general,"doing search on store = " + store.getentitystorename()); IStorageSearchResultSet storresultset = StorageSearchHome.search(store, query, null, connectorinfo); try { appcb.logln(ilog.log_general, "Resultset " + storresultset.getcount() + ", rawquery="+storresultset.getquery()); int i = 0; while(storresultset.hasnext()){ IStorageItemVersion siv = storresultset.next(); if(i++ < 100){ 31

33 Quick Start appcb.logln(ilog.log_general, "StorageItemVersion : [" + ((ZStorageItemVersion)siv).getPersistent()+"]"); else { appcb.logln(ilog.log_general, siv.getitemversionkey()); File filedir = new File(stFileDir); if(ast.length > 2){ //download String stfiledir = ast[3]; FileUtil.mkdirs(fileDir); OutputStream os = null; InputStream is = null; try { os = new FileOutputStream(new File(fileDir,siv.getItemVersionKey()+siv.getName())); finally { is = siv.getcontent(); MiscUtil.pumpIO(is,os); os.flush(); MiscUtil.closeQuiet(is); MiscUtil.closeQuiet(os); catch(throwable t1){ t1.printstacktrace(); finally { if(storresultset!= null){ storresultset.close(); 32

34 Quick Start catch(throwable t){ t.printstacktrace(); System.out.println("Exiting.."); Searching Storage package samples.com.zlti.zlservices; import java.io.file; import java.io.fileoutputstream; import java.io.inputstream; import java.io.outputstream; import java.util.date; import wsi.io.fileutil; import wsi.services.iappcallback; import wsi.services.threadcontext; import wsi.util.ilog; import wsi.util.miscutil; import com.ziplip.zlcp.util.iconnectorinfo; import com.zlti.zlsimpl.app.storage.zstorageitemversion; import com.zlti.zlservices.app.storage.istorageitemversion; import com.zlti.zlservices.app.storage.istoragesearchresultset; import com.zlti.zlservices.app.storage.storagesearchfields; import com.zlti.zlservices.app.storage.storagesearchhome; import com.zlti.zlservices.core.zlclientserviceshome; import com.zlti.zlservices.core.search.isearchcondition; import com.zlti.zlservices.core.search.isearchquery; 33

35 Quick Start import com.zlti.zlservices.core.search.isearchstore; public class StorageSearch { public static void main(string[] ast){ if(ast.length < 4){ System.out.println("Usage : java prgname url certfile certpwd downloaddir"); return; try { ZLClientServicesHome.init(new File("log")); ZLClientServicesHome.initThread(); IAppCallback appcb = ThreadContext.getApp(); String sturl = ast[0]; String stcertfile = ast[1]; String stcertpwd = ast[2]; IConnectorInfo connectorinfo = ZLClientServicesHome.getConnectorInfo(stUrl, stcertfile, stcertpwd); ISearchQuery query = StorageSearchHome.createSearchQuery(); ISearchCondition condbody = query.makeanyphrasecondition(storagesearchfields.field_name, "exec_2_ _210649"); ISearchCondition condsize = query.makerangecondition(storagesearchfields.field_size, 1, 5); ISearchCondition conddate = query.makerangecondition(storagesearchfields.field_create_d ATE, new Date(System.currentTimeMillis() - 365L*86400L*1000L), new Date()); ISearchCondition condcombined = query.combine(isearchquery.comb_opid_and, new ISearchCondition[]{condBody,condSize,condDate); 34

36 Quick Start query.close(condcombined); ISearchStore[] astores = StorageSearchHome.getAllSearchStores(connectorInfo); for(isearchstore store : astores){ appcb.logln(ilog.log_general,"doing search on store = " + store.getentitystorename()); IStorageSearchResultSet storresultset = StorageSearchHome.search(store, query, null, connectorinfo); try { appcb.logln(ilog.log_general, "Resultset " + storresultset.getcount() + ", rawquery="+storresultset.getquery()); int i = 0; while(storresultset.hasnext()){ IStorageItemVersion siv = storresultset.next(); if(i++ < 100){ else { appcb.logln(ilog.log_general, "StorageItemVersion : [" + ((ZStorageItemVersion)siv).getPersi stent()+"]"); appcb.logln(ilog.log_general, siv.getitemversionkey()); if(ast.length > 2){ //download String stfiledir = ast[3]; File filedir = new File(stFileDir); FileUtil.mkdirs(fileDir); OutputStream os = null; InputStream is = null; try { is = siv.getcontent(); 35

37 Quick Start finally { os = new FileOutputStream(new File(fileDir,siv.getItemVersi onkey()+siv.getname())); MiscUtil.pumpIO(is,os); os.flush(); MiscUtil.closeQuiet(is); MiscUtil.closeQuiet(os); catch(throwable t1){ t1.printstacktrace(); finally { if(storresultset!= null){ storresultset.close(); catch(throwable t){ t.printstacktrace(); System.out.println("Exiting.."); 36

38 Using ZL API Kit Resources 3 Using ZL API Kit Resources 3.1 Using the API Kit with Java and.net Server and Account Requirements A server and a user account are required to invoke server functionalities. It is essential that you use a compatible ZL API Kit library to connect to the server. A user needs to be provisioned by a ZL UA administrator. To connect as that user the following are required: The URL of the server User account and password Server Configuration There is no additional configuration required other than the user provisioning mentioned in the above section Security Client applications often require limited access to a user's ZL Account for certain types of activity. Access control has two components, authentication and authorization. Authentication services allow users to sign in to ZL UA application using an account. Authorization services let users provide the application with access to the data they have stored in ZL UA. Authentication and authorization services are often referred to collectively as auth. ZL UA ensures all internal and external connections go through an appropriate and adequate form of authentication. We need to be assured that this control cannot be bypassed. All pages in ZL UA enforce this requirement for authentication. Additionally, we need to ensure that authentication credentials do not traverse the wire in clear text format. ZL UA ensures that there are authorization mechanisms in place and that the modules/application has clearly defined the user types/roles and responsibilities and the rights of said users. The goal is to ensure there is a least privilege stance in operation and cannot be circumvented. For more details, refer to the Roles and Privileges section below. While ZL UA itself supports a variety of authentication mechanism, the clients that need access to ZL UA is authenticated using OAuth mechanism. For details refer to Step One of the Quick Start section in Chapter 2 above Roles and Privileges ZL UA allows for privileges and roles to be assigned to users based on their roles in the organization. For example, access privileges in an application differ for Department Reviewers, Compliance Administrators, Compliance Auditors, and Reviewer Administrators. It is important to understand the difference between a role and a privilege as these terms are used in various places throughout the manual. 37

39 Using ZL API Kit Resources Role A role is the function of an individual, independent of any conditions. It is not based on any other resource or entity. Examples of roles include Compliance Administrator, Auditor, and Reviewer Administrator. Roles can also be managed through Group Membership in Active Directory or Domino Directory. This allows for central management of user access levels Privilege A Privilege is an additional resource given to an individual, in addition to their regular role. Reviewer is identified as a privilege by the application. There are two types of roles available within ZL UA. 1. System Roles: ZL UA provides standard roles such as Super administrator, System Administrator, Domain Administrator etc. along with control on the grantable roles and each role has a specific set of allowed operations. 2. Custom Roles: ZL UA allows you to define custom roles by modifying or combining system roles. Follow these steps to create a custom role. You can harden the ZL UA system by providing only relevant roles and privileges to the end users. You can also create and provide custom roles in case a straight system role cannot be granted. Refer to System and Custom Roles in ZL Unified Archive technical note for more details on Roles and Privileges ad how to create custom roles to further harden the ZL UA system. Super Administrator is a very powerful system role and this role has to be provided very carefully to the users. If an operation is user-specific, such as reading the user address book or composing mail on behalf of the user, the success of this method depends on the privileges of the logged-in user. During each ZL API Kit call, the session handle is verified for the privileges. ZL recommends that you assign a special account for the ZL API Kit user and give it the appropriate role/privilege. For example, you can grant the Domain Admin privilege if the ZL API Kit client needs to perform user based operations. Finally, depending on the operation, the code might look for additional privileges. For example, to use the ZL API Kit to create users, the users need to have Domain Admin privilege pertaining to the domain of the new user. 3.2 Initialization Follow these instructions to create a session with the ZL server using the API Kit. Every thread that is being spawned to perform certain API calls to the ZL server needs to be initialized as well as a directory needs to be set for API logging. These are ensured as follows: ZLClientServicesHome.init(fileLogDir); 38

40 Using ZL API Kit Resources ZLClientServicesHome.initThread(); The first line above - ZLClientServicesHome.init -- initializes a logging directory for the API logging. If the directory does not exist, it will be created. In Java, filelogdir is a java.io.file object representing a directory under which each thread invoked in this application writes a log file of its own, while in.net, filelogdir is a System.IO.DirectoryInfo object. For example in Java, this can be done as ZLClientServicesHome.init(new File( C:\\ZLAPIKit\\log )); Similarly in.net, this can be done as ZLClientServicesHome.init(new System.IO.DirectoryInfo( C:\\ZLAPIKit\\log )); The log files have a prefix of zservlog. The second line above - ZLClientServicesHome.initThread initializes certain core functionalities like client session management, network connectivity, etc. The above two initializations are needed only once per every thread invoked. More on this can found in the samples. 3.3 IConnectorInfo This is the basic object that is needed for all the API calls. This object provides the network connectivity to the ZL server as well as the user authentication based on the certificate issued by the ZL server. An instance of this object can be created by using this line: IConnectorInfo connectorinfo = ZLClientServicesHome.getConnectorInfo(stUrl, stcertfile, stcertpwd); where sturl is the URL of the ZL server as explained above, stcertfile is the ZL server issued certificate file and stcertpwd is the password used to encrypt the certificate. Once an instance of this IConnectorInfo object is created, the same object can be reused in many API calls to the ZL server as long as the calls are to the same ZL server under the same user context. This object is thread safe and the need for an instance of this object raises only when the client needs to talk to another ZL server or when the user context has to change (a different certificate has to be used at that point). Clients can cache the instance of this object and reuse it in as many API calls as they can in an asynchronous way. For a typical single ZL system access, you may just need a single user API Kit connection and correspondingly one URL, one certificate file with its password. However, in a migration scenario, the API Kit could be running on a third machine i.e. between a source ZL system and a destination ZL system. In this case, you need separate connections, one to source and another to destination, and they need their respective URLs, certificate(s)/password(s). 39

41 Using ZL API Kit Resources For example, a particular archive user can be obtained using his alias with the following API: IArchiveUserInfo aui = CoreHome.getUserUsingAlias(stAliasAddress, connectorinfo); where connectorinfo is the instance of IConnectorInfo created above. 3.4 And Now Some Services Listing Archive Departments The following code snippet illustrates how to list archive departments using the API Kit: String stdepartmentpattern = "%"; IDepartmentInfo[] adepts = CoreHome.getAllDepartmentsUsingNameSearch( stdepartmentpattern, connectorinfo); for (int i=0; i < adepts.length; i++) { System.out.println(aDepts[i].getName() + ","+ adepts[i].getdomain()); The above code snippet assumes that the instance of IConnectorInfo object (connectorinfo) is already created as described in the earlier section while using the getalldepartmentsusingnamesearch() API call in CoreHome. The application invokes the getalldepartmentsusingnamesearch() method to retrieve an array of IDepartmentInfo objects that contain the department names available. The method takes a pattern string that accepts SQL wildcards, so % matches all possible values. 40

42 How to Use the ZL API Kit 4 How to Use the ZL API Kit 4.1 Object Schema Figure 7 ZL UA Object Schema 4.2 ZL Services Core Packages This chapter provides some tips on how to use the ZL API Kit. 41

43 How to Use the ZL API Kit IDepartmentInfo represents a Department equivalent on the ZL server. IMailServerInfo represents a Mail Server equivalent on the ZL server. IArchiveUserInfo represents a User equivalent on the ZL server. IArchiveUserAliasInfo represents a user alias equivalent on the ZL server. connectorinfo used in the following code snippets is an instance of IConnectorInfo that is described in the earlier chapter. The instance of this IConnectorInfo can be generated once and can be used in many API calls without generating a new one. IConnectorInfo is a fundamental object for ZL API calls and needed by almost all of them. 4.3 Department Administration Getting a Department The following methods enable you to get a Department. 1. Get the Department using name. IDepartmentInfo deptinfo = CoreHome.getDepartmentUsingName(stDeptName, connectorinfo); where stdeptname is a String representing the name of the department and connectorinfo is the instance of IConnectorInfo. 2. Get the Department using internal identifier. IDepartmentInfo deptinfo = CoreHome.getDepartmentUsingId(idDeptInfo, connectorinfo); where iddeptinfo is an integer representing the internal identifier of the department. 3. Get the child Departments of a specified Department. IDepartmentInfo[] adeptinfo = deptinfo.getallchildren(); where deptinfo is the instance of the IDepartmentInfo whose child department we are looking for. 4. Get the parent Department of a specified Department. int idparentdept = deptinfo.getparentdepartmentid(); IDepartmentInfo deptinfoparent = CoreHome.getDepartmentUsingId(idParentDeptInfo,connectorInfo); where deptinfo is the instance of IDepartmentInfo whose parent department we are looking for Finding a Department When you get a list of Departments, you can use SQL wildcards (?, %) for pattern matching. 42

44 How to Use the ZL API Kit To get a list of Departments: Get the list of available Departments, IDepartmentInfo[] adeptinfo = CoreHome.getAllDepartmentsUsingNameSearch(pattern, connectorinfo); Creating a Department ZL server maintains a hierarchy of departments and hence any new department can only be created under an already existing department. The creation of the top level department (root as we denote) is not allowed through these API calls. In essence, we assume the root to be already existent. To create a new department with name stdeptnew under an existing department with name stdeptparent, the following must be done: IDepartmentInfo deptinfoparent = CoreHome. getdepartmentusingname(stdeptparent, connectorinfo); deptinfoparent.createchilddepartment(stdeptnew, stdisplayname, stdomainname, stclassifiername, stexternalreference, stmiscfield1, stmiscfield2); Updating a Department Fields such as department name, display name, classifier name, external reference and other miscellaneous fields can be updated on the department as shown below, IDepartmentInfo deptinfo = CoreHome.getDepartmentUsingName(stDeptName, connectorinfo); deptinfo.update(stnamenew, stdisplaynamenew, stclassifiernamenew, stexternalreferencenew, stmiscfield1new, stmiscfield2new); Deleting a Department To delete a Department with name stdeptname, IDepartmentInfo deptinfo = CoreHome.getDepartmentUsingName(stDeptName, connectorinfo); deptinfo.delete(); 4.4 Mail Server Administration Mail Servers where users are discovered and archived from are represented by IMailServerInfo object. 43

45 How to Use the ZL API Kit Getting a Mail Server The following methods enable you to get a mail server. 1. Get the mail server using name. IMailServerInfo mailserverinfo = CoreHome. getmailserverusingname(stmailservername, connectorinfo); where stmailservername is a string representing the name of the mail server. 2. Get the mail server using internal identifier. IMailServerInfo mailserverinfo = CoreHome. getmailserverusingid(idmailserver, connectorinfo); where idmailserver is an integer representing the internal identifier of the mail server Finding a Mail Server When you get a list of mail servers, you can use SQL wildcards (?, %) for pattern matching. To get a list of mail servers, IMailServerInfo[] amailserverinfo = CoreHome.getAllMailServerUsingNameSearch(pattern, connectorinfo); Creating a Mail Server Creating a mail server in ZL means creating reference to an external mail server from which users are discovered for archiving and journaling purposes. Hence this needs to have valid URL and a valid user discovery object name. Mail servers of three types (Microsoft Exchange, Lotus Domino and Google) are allowed to be created. IMailServerInfo mailserverinfo = CoreHome.creat Server(stMailServerType, stmailservername, stmailserverurl, stdiscoveryname, mapparam, connectorinfo); where stmailservertype is a constant for type of mail server defined at com.zlti.zlservices.core.zlconstants.mailservertypeconstants.provider _*., stmailservername is the name of the mail server, stmailserverurl is a valid URL of the mail server, stdiscoveryname is the name of the user discovery object available on the ZL Server that this mail server need to be associated with for discovering users, mapparam is an instance of java.util.map providing miscellaneous mail server properties in a key-value fashion. ZL Server requires few specific properties be specified in the mapparam for each kind of mail server. The specific properties for each kind of mail server are detailed in the Java doc around this API. 44

46 How to Use the ZL API Kit 4.5 User Administration Getting an Archive User Invoke the following methods to get an archive user: To get an archive user, there are five indexed fields you can use, 1. To get the user using the unique primary address field of the user, staddress, IArchiveUserInfo aui = CoreHome.getUserUsingAddress(stAddress, connectorinfo); 2. To get the user using any of user s alias addresses, staliasaddress, IArchiveUserInfo aui = CoreHome.getUserUsingAlias(stAliasAddress, connectorinfo); 3. To get the user using a unique external reference such as a GPIN, stexternalreference, IArchiveUserInfo aui = CoreHome.getUserUsingExternalReference(stExternalReference, connectorinfo); 4. To get the user using the unique owner field. The owner can be the UUNAME. IArchiveUserInfo aui = CoreHome.getUserUsingOwner (stowner, connectorinfo); 5. To get the user using the unique ZL s internal user identifier, idzlpuser, IArchiveUserInfo aui = CoreHome.getUserUsingZlpUserId (idzlpuser, connectorinfo); Finding Archive Users by Department ZL s object model is such that users can only exist in a department. Hence to get to all the users in the department named stdeptname, it is necessary to get to the department object which provides the service of getting to all users inside as shown below, IDepartmentInfo deptinfo = CoreHome.getDepartmentUsingName(stDeptName, connectorinfo); IArchiveUserInfo[] aarchuserinfo = deptinfo.getallusers(); 45

47 How to Use the ZL API Kit Creating a User Account Since users in ZL cannot exist without a valid department, the object IDepartmentInfo provides the service of creating a new user into ZL under that particular department as follows, IDepartmentInfo deptinfo = CoreHome.getDepartmentInfoUsingName(stDept, connectorinfo); IArchiveUserInfo archusercreated = deptinfo.createuser(staddress, stowner, stexternalreference, stfullname, iusertype, datehire, fterminated, dateterminated, stmiscfield1, stmiscfield2, fsyncexcluded); where stowner is a unique field containing information about the user, such as a UUNAME, stexternalreference is an external mail server reference, such as a tracking identifier or GPIN, iusertype is the user type from com.zlti.zlservices.core.zlconstants.usertypeconstants.type_*, staddress is the user s e- mail address, stfullname is the user s full name, datehire is the date the user started with your organization, fterminated is a boolean value representing if the user is terminated, dateterminated is a date value representing the terminated date of the user, fsyncexcluded is a boolean value representing if you wish to exclude this user from LDAP synchronization or any other synchronization, stmiscfield1 and stmiscfield2 are user defined string fields that can be used for extra information. For creating a group, the iusertype should be Checking if a User is a Group In ZL, even groups are added as users. To check whether the user is a group, IArchiveUserInfo aui = CoreHome.getUserUsingAlias(stAliasAddress, connectorinfo); Boolean fvalue = aui.isgroup(); where staliasaddress is the user s alias address, and connectorinfo is an instance of IConnectorInfo Getting All Group Members To get all of the members in the group, IArchiveUserInfo aui = CoreHome.getUserUsingAlias(stAliasAddress, connectorinfo); aui.getgroupmembers(); 46

48 How to Use the ZL API Kit Adding a Member to the Group To add a member to the group, IArchiveUserInfo aui = CoreHome.getUserUsingAlias(stAliasAddress, connectorinfo); aui.addgroupmember(stalias, stname, st address); Removing a Member from the Group To remove a member from the group, IArchiveUserInfo aui = CoreHome.getUserUsingAlias(stAliasAddress, connectorinfo); aui.removegroupmember(staliasaddress); Updating a User s Profile IArchiveUserInfo object provides five methods for updating different parts of user profile as shown below, 1. To update the user account information, archuserinfo.updateaccountinfo(stexternalreference, stfullname, datehire, stmiscfield1, stmiscfield2); 2. To update the user s primary address, archuserinfo.updateaddress(staddress); 3. To update the user s mail server account information, archuserinfo.updat serverinfo(stmailservername, stmailstoreinfo, stconnectuserid, stconnectpassword); 4. To update the owner field that uniquely identifies the archive user, archuserinfo.updateowner(stowner); 5. To update the field that determines if the user fields will be synchronized with LDAP, archuserinfo.updatesyncexclude(fsyncexclude); where fsyncexclude is true if the synchronization is needed, else false. In all the update methods demonstrated above, archuserinfo is an instance of IArchiveUserInfo that needs to be updated and can be fetched using any of the get methods explained in the previous sections. 47

49 How to Use the ZL API Kit Terminating a User Account To terminate a user account, archuserinfo.terminateuser(dateterminated); where dateterminated is the date on which the user is terminated. This API call will mark the user as terminated which then puts the termination date on the user fields Restoring a Terminated User Account To restore a terminated user account, archuserinfo.restoreterminateduser(daterestored, frestoreaddress, frestoreavailablealiases); where daterestored is the date on which the terminated user is restored, frestoreaddress is a boolean field which indicates whether this user s address needs to be restored and frestoreavailablealiases is a boolean field which indicates whether all the available aliases of this terminated user needs to be restored. Calling this API on a non-terminated user will not result in any action on the user profile on the ZL server Deleting an Archive User Account User account deletion can be done as follows: archuserinfo.delete(); Creating a Child Department Creating a child department can be done as follows: IDepartmentInfo deptinfoparent = CoreHome.getDepartmentInfoUsingName(stParentDeptName); deptinfo.createchilddepartment(stname, stdisplayname, stdomainname, stclassifiername, stexternalreference, stmiscfield1, stmiscfield2); Moving User to a New Department To move user to a new Department, IDepartmentInfo deptinfonew = CoreHome.getDepartmentInfoUsingName(stNewDeptName); (Optional step) IDepartmentInfo deptinforeview = CoreHome.getDepartmentInfoUsingName(stReviewDeptName); 48

50 How to Use the ZL API Kit archuserinfo.movedepartment(deptinfonew, reviewdeptinfo); In the above, if there is no review department update, reviewdeptinfo can be sent as null Managing User Aliases Access to all the aliases of a given user are provided through the IArchiveUserInfo object in this way, IArchiveUserAliasInfo[] aarchuseralias = archuserinfo.getalluseraliases(); To add a particular alias to a user profile, IArchiveUserAliasInfo archuseralias = archuserinfo.adduseralias(stalias, ialiastype); where stalias is the new alias that is being added to the existing user archuserinfo and ialiastype is an integer variable indicating the type of this alias. The values of allowed alias types are from com.zlti.zlservices.core.zlconstants.aliastypeconstants.alias_type_*. This API returns the newly added user alias object as IArchiveUserAliasInfo. To remove a particular alias on a user profile, archuserinfo.removeuseralias(stalias); Managing Reviewers on a Department Reviewers are essentially user profiles in the system, which are given a special role to review mails of a particular department in the Compliance module of the ZL Unified Archive Platform. Given a department, all the user profiles that are assigned as reviewers of this department can be obtained as follows, IArchiveUserInfo[] aarchuserinforeviewer = deptinfo.getallreviewers(); where deptinfo is an instance of IDepartmentInfo. A particular user can be added as a reviewer to a given department as follows, IArchiveUserInfo[] aarchiveuserinfo = new IArchiveUserInfo[] {archuserinfo; deptinfo.addreviewers(aarchiveuserinfo); Similarly a user can be removed as reviewer on a given department as follows, IArchiveUserInfo[] aarchiveuserinfo = new IArchiveUserInfo[] {archuserinfo; 49

51 How to Use the ZL API Kit deptinfo.removereviewers(aarchiveuserinfo); IDepartmentInfo provides the service of adding or removing an array of users (instance of IArchiveUserInfo) as reviewers. 4.6 Role Administration Use these methods for granting or revoking custom role privileges Listing all System Roles To list all the system roles on a system, IRoleDescriptor[] systemroledescriptors = CoreHome.getAllSystemRoleDescriptor(connectorInfo); Listing all Custom Roles To list all the custom roles, IRoleDescriptor[] systemroledescriptors = CoreHome.getAllCustomRoleDescriptor(connectorInfo); Listing System Roles Assigned to a User To list all the roles assigned to a specific user, IUserRole[] auserrole = archuserinfo.getallroles(); Making a Role to Assign or Revoke To make a role object to assign or revoke on a specific user, IUserRole userrole = CoreHome.makeUserRole(roleDescriptor, stscope, adeptinfo); Where stscope is a parameter of String type whose values are from the com.zlti.zlservices.core.zlconstants.userroleconstants.scope_type_* and adeptinfo is an array of IDepartmentInfo (department) in which this role is given/revoked on the user. If a role is intended to be applicable on all the departments recursively, the scope of such a role is com.zlti.zlservices.core.zlconstants.userroleconstants.scope_type_global and the adeptinfo is null as below, IUserRole userroleglobal = CoreHome.makeUserRole(roleDescriptor, com.zlti.zlservices.core.zlconstants.userroleconstants.scope_type_glob AL, null); Once a IUserRole is generated, it is granted to a specific user, IUserRole[] auserrolegrant = new IUserRole[] {userrole; 50

52 How to Use the ZL API Kit archuserinfo.grantroles(auserrolegrant); In the same way, roles can be revoked on a specific user like this, IUserRole[] auserrolerevoke = new IUserRole[] {userrole; archuserinfo.revokeroles(auserrolerevoke); Archived Folder Navigation on a Specific User Once a user s mail is archived from the mail server, the user s mail in ZL Unified archive is archived into the same folder hierarchy that appears on the user s mailbox on the mail server. The top level archived folders (also referred to as root level folders) on ZL can be obtained on a specific user as follows, IFolderInfo[] afolderinforoot = archuserinfo.getmailboxfolders(); If the user is not yet archived by ZL, the folder hierarchy does not exist and the above API call will result in a null return. Each instance of the IFolderInfo object represents an archived folder for a specific user and if the folders are nested deep, subsequent child folders of a given folder can be obtained as follows, IFolderInfo[] afolderchild = folderroot.getchildfolders(); Where folderroot is one of the root folders returned from the API call that returns an array of root level folders and afolderchild is a returned array of child folders. If there are no child folders for folderroot the call returns a null array. If the entire archived folder structure of user is desired, the getchildfolders() function needs to be called recursively over every child folder until the API returns null. To recursively collect the entire folder structure of a given user, IFolderInfo[] afolderinforoot = archuserinfo.getmailboxfolders(); List<IFolderInfo> listallfolders = new ArrayList<IFolderInfo>(); if(afolderinforoot!= null){ for(ifolderinfo folderinfo : afolderinforoot){ addchildrecursively(folderinfo, listallfolders); void addchildrecursively(ifolderinfo folderinfo, List<IFolderInfo> list) { list.add(folderinfo); 51

53 How to Use the ZL API Kit IFolderInfo[] folderinfochild = folderinfo.getchildfolders(); if(folderinfochild!= null) { addchildrecursively(folderinfochild, list); If a parent folder of a specific folder is desired, it can be obtained on the child folder as follows, IFolderInfo folderparent = folderchild.getparentfolder(); If the child folder used in the above API call is already a root level folder, the API call will result in a null return value for the parent folder Archived Mail Navigation through a User s Folder Once the folder information of a specific user is obtained using one of the API calls described in the previous section, the archived mails contained in that particular folder can be obtained as follows, IMessageResultSet msgresultset = folderinfo.getfoldermessages( stsortfield, fascending); where IMessageResultSet is a result set of message objects contained in that particular folder, stsortfield is a String field on which this result set is sorted and fascending is a boolean value which indicates whether the sorting on the sort field will be in ascending or descending order. If the order desired is ascending, the value of this parameter should be true else false. The values of valid sort fields supported by this API are from com.zlti.zlservices.app.mail.ifolderinfo.sort_*. If no sorting is desired, the value of this sort field should be passed as com.zlti.zlservices.app.mail.ifolderinfo.sort_none. The IMessageResultSet object offers three important API calls (hasnext(), next() and close()) that are used to navigate through all the messages that the object represents. The following code snippet walks through all the messages in a folder using the IMessageResultSet object on that folder: IMessageResultSet msgresultset = folderinfo.getfoldermessages(stsortfield, fascending); while(msgresultset.hasnext()) { IZLPMessage zlpmessage = msgresultset.next(); // Custom code here to use IZLPMessage msgresultset.close(); 52

54 How to Use the ZL API Kit The next() on the IMessageResultSet object returns an instance of the IZLPMessage object, which is the fundamental client object uniquely representing an that is archived by the ZL server. 4.7 Searching for Mails Mails that are archived as well as journaled by the ZL server are indexed into search stores, which can be searched for mails. Separate search stores are created for indexing archived mails and journaled mails. These search stores for s can be obtained as follows, ISearchStore[] asearchstore = MessageSearchHome.getAllSearchStores(fJournalStores, farchivestores, connectorinfo); where fjournalstores is a boolean variable representing whether to get search stores containing journaled mails, farchivestores is a boolean variable representing whether to get search stores containing archived mails, and connectorinfo is the instance of IConnectorInfo. Once the search stores are obtained, queries can be issued on this search store to retrieve the s resulting from the search. Search query is an object with one or many search conditions that are combined with three operators, AND, OR, NOT Creating a Search Condition To create a search condition, ISearchQuery query = MessageSearchHome.createSearchQuery(); The above returns a search query which has no conditions inside it. Feeding this object to the server for search results in an exception from the ZL server. To create a search condition on the message body looking for the word test, ISearchCondition condbody1 = query.makeanyphrasecondition(messagesearchfields.field_body, "test"); ISearchCondition condbody2 = query.makeexactphrasecondition(messagesearchfields.field_attachment, "any of"); To combine the previous two constructed search conditions with an OR operator, which means searching for mails with phrase test in the body or the exact phrase any of in any of the mail s attachments, ISearchCondition condbody = query.combine(isearchquery.comb_opid_or, new ISearchCondition[]{condBody1,condBody2); (.Net) 53

55 How to Use the ZL API Kit ISearchCondition condbody = query.combine(zsearchquery.comb_opid_or, new ISearchCondition[]{condBody1,condBody2); To create a search condition on the message size with sizes between 1KB (1024B) and 1MB (1024 * 1024), ISearchCondition condsize = query.makerangecondition(messagesearchfields.field_message_size, 1024, 1024 * 1024); To create a search condition on the message date with dates in the last year, ISearchCondition conddate = query.makerangecondition(messagesearchfields.field_msg_date, new Date(System.currentTimeMillis() - 365L*86400L*1000L), new Date()); To combine the previous three conditions (the combined body condition, the size condition, and the date condition) with an AND operator, which means searching for all mails that have the phrase test in the body or the phrase any of in the attachment and whose size lie between 1KB and 1MB and whose date happens to be in the last year, ISearchCondition condcombined = query.combine(isearchquery.comb_opid_and, new ISearchCondition[]{condBody,condSize,condDate); (.Net) ISearchCondition condcombined = query.combine(zsearchquery.comb_opid_and, new ISearchCondition[]{condBody,condSize,condDate); To close the combined condition on the search query, query.close(condcombined); A search query object (ISearchQuery) is not a valid query at the ZL server until and unless it is closed before sending it to the ZL server. All the various fields of the message on which ISearchCondition can be obtained are from com.zlti.zlservices.app.mail.messagesearchfiels.field_* Navigating through Mails from the Search Result Once the search store and query have been constructed, mails resulting from this query can be obtained as follows, IMessageSearchResultSet msgsearchresultset = MessageSearchHome. search(searchstore, srchquery, afieldvaluehistogram, connectorinfo) where IMessageSearchResultSet is a result set of message objects. 54

56 How to Use the ZL API Kit The IMessageSearchResultSet object offers three important APIs (hasnext(), next() and close()) that are used to navigate through all the messages that the object represents. The following code snippet walks through all the messages resulting from the search: IMessageSearchResultSet msgsearchresultset = search(searchstore, srchquery, afieldvaluehistogram, connectorinfo); while(msgsearchresultset.hasnext()) { IZLPMessage zlpmessage = msgresultset.next(); // Custom code here to use IZLPMessage msgsearchresultset.close(); The next() on the IMessageSearchResultSet object returns an instance of the IZLPMessage object, which is the fundamental client object uniquely representing an that is archived by the ZL server. 4.8 Message Handling Downloading Message Once the message object (IZLPMessage) is obtained, the actual message content can be downloaded in the form of standard java object InputStream as shown below, InputStream ismessagecontent = zzlpmsg.getcontent(itype); where zzlpmsg is the instance of IZLPMessage object obtained from the ZL server and itype is the integer variable indicating the type of content required and is one of the values from com.zlti.zlservices.app.mail.izlpmessage.output_*. For now the only value of itype supported is OUTPUT_MIME, which fetches the standard mime content of the message as an input stream Uploading Message Uploading a message to the ZLserver can be achieved by using the object IMessageUpload. An instance of this IMessageUpload can be obtained as shown below, IMessageUpload msgupload = MessageHome.uploadMessage(iUploadType, imessagetype, fmigration, stsourceinfo, stsourcemiscinfo, connectorinfo); where iuploadtype is an integer value representing the type of message content that is being uploaded and is given in com.zlti.zlservices.app.mail.messagehome.mailuploadconstants.upload_type_*, 55

57 How to Use the ZL API Kit imessagetype is the type of the message and should be one of the valid ZL message types as defined in com.zlti.zlservices.app.mail.messagetype, fmigration is the boolean value representing whether the uploaded message is for migration purposes, stsourceinfo is a String value notifying the server of the message s source which can be used for tracking as well as reporting purposes, stsourcemiscinfo is another String value to put any marker on the uploaded message which can be used for tracking and reporting on the ZL server, connectorinfo is the instance of the IConnectorInfo explained in the earlier section. For example, if an Exchange mail is being uploaded for journaling purpose to the ZL server, value of imessagetype is com.zlti.zlservices.app.mail.messagetype.exchange_journal_mail and if a Lotus mail is being uploaded for archiving purpose to the ZL server, the value of imessagetype is com.zlti.zlservices.app.mail.messagetype.lotus_archive_mail. Once the instance of IMessageUpload is obtained, if message level envelope headers need to be set, it can be done as follows, msgupload.setenvelopefrom(stenvelopefromlist); msgupload.setenveloperecipients(stenvelopercptlist); If the uploaded message needs to be processed, stored and associated with a particular department on the ZL server, the store level department can be set on this IMessageUpload as follows, msgupload.setstoredepartment(ststoredepartment); where ststoredepartment is the name of the department (IDepartmentInfo). In addition to the above, if the message is being uploaded for archiving purpose, the user on ZL for whom the mail is being uploaded and archived for, also needs to be specified. This can be done as follows, msgupload.setrecipientinfo(recipientinfo); where recipientinfo is an instance of RecipientInfo object. It can be obtained as follows, RecipientInfo recipientinfo = new RecipientInfo(user1@domain.com, Inbox\\Upload ); where user1@domain.com is the address of the user on ZL (IArchiveUserInfo) and Inbox\\Upload is the folder path where the archive mail is going to reside for the user. Once the mail is uploaded and successfully processed, the mail can be seen at this folder on for the user in the ZL End User Mailbox Access module of the ZL Web UI. Once the appropriate recipient level, store level and message header level properties are set on the IMessageUpload, the actual message content can be uploaded by getting the TransactionOutputStream on the IMessageUpload object as follows, 56

58 How to Use the ZL API Kit TransactionOutputStream tos = msgupload.getuploadstream(); where tos is the instance of TransactionOutputStream which is a ZL client object extending Java OutputStream. The TransactionOutputStream provides a special service of aborting the stream (transaction) if needed. If an error is detected while writing the content to this TransactionOutputStream, the stream can be aborted which prevents the transaction from uploading incomplete data to the ZL server as follows, tos.abort(); Once the TransactionOutputStream has been closed and the content has been successfully uploaded, ZL server acknowledges the accepted content/message with a unique received mail identifier (string id) which can be used to track the message on the ZL server from then on. This received mail identifier can be obtained on the IMessageUpload as follows, String strmid = msgupload.getreceivedmailid(); The above method for getting the received mail identifier should only be called after a successful message content upload (i.e. after closing the TransactionOutputStream), otherwise this API call results in an exception. To upload a message to the ZL server,imessageupload msgupload = MessageHome.uploadMessage(iUploadType, imessagetype, fmigration, stsourceinfo, stsourcemiscinfo, connectorinfo); msgupload.setenvelopefrom(stenvelopefromlist); msgupload.setenveloperecipients(stenvelopercptlist); msgupload.setstoredepartment(ststoredepartment); // If archive message.. RecipientInfo recipientinfo = new RecipientInfo(user1@domain.com, Inbox\\Upload ); msgupload.setrecipientinfo(recipientinfo); TransactionOutputStream tos = msgupload.getuploadstream(); // C:\\MimeMessage.txt contains the mime content of the message to be uploaded InputStream ismimemessagecontent = new FileInputStream(new File( C:\\MimeMessage.txt )); try { // custom code stream ismimemessagecontent to tos ; 57

59 How to Use the ZL API Kit // tos.close(); catch (Exception e){ tos.abort(); throw e; finally { ismimemessagecontent.close(); String streceivedmailid = msgupload.getreceivedmailid(); 58

60 File Archiving & Storage Related API 5 File Archiving & Storage Related API Note The following components of ZLServices API Kit have to be considered experimental features, even if they are part of a "stable" release or an official version. If you use any of these features then you have to be aware that they may be incomplete in their implementation, have known issues, or their design and programming interface is subject to change in the future, so it may require you to adapt your experiment code to the changing interface when upgrading to a future release of ZLServices API Kit. 5.1 Object Schema Figure 8 File Archiving and Storage Related Object Schema 59

61 File Archiving & Storage Related API 5.2 ZLServices Files and Storage Packages This chapter provides some tips on how to use the ZL API Kit for archiving files and managing file archiving module of ZL Unified Archive Suite. The above chart shows the object schema flow. IStorageProjectInfo represents a root level container (Storage Projects) on ZL, which corresponds to a top level file directory which is archived. IStorageFolderInfo represents folders under projects which are organized as tree structure representing the physical file directory hierarchy. IStorageItem represents files in a folder that are archived. IStorageItemVersion represents the versions of the files that are archived. 5.3 Project Administration Getting a Project The following methods enable you to get a Project. 1. Get the Department using name. IStorageProjectInfo projectinfo = StorageHome.getProjectUsingName(stName, connectorinfo); where stname is a String representing the name of the project and connectorinfo is the instance of IConnectorInfo. 2. Get the Project using internal identifier. IStorageProjectInfo projectinfo = StorageHome.getProjectUsingId(idProject, connectorinfo); where idproject is an integer representing the internal identifier of the Project Finding a Project When you get a list of Projects, you can use SQL wildcards (?, %) for pattern matching. To get a list of Projects: Get the list of available Departments. IStorageProjectInfo[] aprojinfo = StorageHome.getAllProjectsUsingNameSearch(stProjectNamePattern, connectorinfo); 60

62 File Archiving & Storage Related API Creating a Project There is no hierarchy of projects on ZL server and hence each project is an independent entity of its own. To create a Project with name stprojectname and display name stprojectdisplayname, IStorageProjectInfo projinfo = StorageHome.createArchiveStorageProject(auiOwner, fileservernode, stprojectname, stprojectdisplayname, iprojecttype, fallowversioning, privileges, fdisablefetchacl, fautosyncacl, dirspec, stlexiconname, connectorinfo); where auiowner is a user (instance of IArchiveUserInfo) that can be obtained using one of the methods explained earlier, fileservernode is the file server (instance of IMailServerInfo) where ZL s connector for a File server/sharepoint server/documentum server resides, iprojecttype is the integer value representing the type of project being created (valid values of project type are defined at com.zlti.zlservices.app.storage.istorageprojectinfo.type_*), fallowversioning is a boolean value notifying if versioning of files inside this project is allowed or not, privileges is the instance of StorageProjectPrivileges which is used to set default privileges for the project which can be created as shown below, fdisablefetchacl is a boolean value set to disable fetching ACL, fautosyncacl is a boolean value used to auto sync ACL flags, dirspec is the instance of IDirectorySpec which contains the specification of directories that are included as well as excluded for archiving files, stlexiconname is used to specify the lexicon name to be applied on that particular project. Although fileservernode is an instance of IMailServerNode, it serves as a File Server Node in the File Archiving module. It notifies ZL server the location of the respective ZL Connector Service, an essential component for archiving files. The fileservernode for the project of type com.zlti.zlservices.app.storage.istorageprojectinfo.type_file can be created as follows, IMailServerInfo fileservernode = StorageHome.createFileServer(stServerName, stipaddress, mapparam, connectorinfo); where stservername is the name of the server, stipaddress is the IP address of the file connector server, and mapparam is an instance of java.util.map providing miscellaneous file server properties in a key-value fashion. ZL Server requires few specific properties be specified in the mapparam for each kind of file server. The specific properties for each kind of file server are detailed in the java doc around this API. The fileservernode for the project of type com.zlti.zlservices.app.storage.istorageprojectinfo.type_sharepoint can be created as follows, 61

63 File Archiving & Storage Related API IMailServerInfo mailservernode = StorageHome.createSharePointServer(stServerName, stserverurl, mapparam, connectorinfo); where stservername is the name of the server, stserverurl of the Sharepoint connector server, mapparam is an instance of java.util.map providing miscellaneous Sharepoint server properties in a key-value fashion. Please refer the java doc around this API for more information about the specific required properties. The fileservernode for the project of type com.zlti.zlservices.app.storage.istorageprojectinfo.type_documentum can be created as follows, IMailServerInfo fileservernode = StorageHome.createDocumentumServer (stservername, stipaddress, mapparam, connectorinfo); where stservername is the name of the server, stipaddress of the Documentum connector server, and mapparam is an instance of java.util.map providing miscellaneous Documentum server properties in a key-value fashion. Please refer the java doc around this API for more information about the specific required properties. IDirectorySpec object can be created as follows, IDirectorySpec dirspec = StorageHome.makeDirectorySpec(aDirEntry); where adirentry is an array of IDirectoryEntry. Each instance of IDirectoryEntry specifies the root directory of files for archiving along with excluded folders. An instance of StorageProjectPrivileges can be created as follows, StorageProjectPrivileges storprojprivs = StorageHome.createStorProjectPrivileges(fAdminPrivilege, freadprivilege, fsearchprivilege, fshareprivilege, fwebdavprivilege, fauditprivilege) Where all the parameters here are boolean values which can be used to create a default StorageProjectPrivileges object which can be used while creating a project. An instance of IDirectoryEntry can be created as follows, IDirectoryEntry direntry = StorageHome.makeDirectoryEntry(stSymbolicLink, stroot, astexlusionrelativepath); Where stsymboliclink is the display name for the root directory on the ZL web UI, stroot is the root directory that needs archiving, astexclusionrelativepath is the array of Strings, each of which are the excluded directories for archiving relative to the root. If a directory entry has no excluded directories, astexclusionrelativepath should be sent as null. 62

64 File Archiving & Storage Related API The following snippet of code illustrates the creation of IDirectorySpec used to create a project: IDirectoryEntry direntry1 = StorageHome.makeDirectoryEntry("public", "\\shared\\users\\public", new String[] {"\\users\\usera","\\users\\userb"); IDirectoryEntry direntry2 = StorageHome.makeDirectoryEntry("private", "F:\\users\\private", new String[] {"\\confidential","\\trash\\junk","\\pictures\\large"); IDirectoryEntry[] adirentry = new IDirectoryEntry[]{ direntry1,direntry2; IDirectorySpec dirspec = StorageHome.makeDirectorySpec(aDirEntry); Updating a File Project To update an archive storage project using the project id. StorageHome.updateArchiveStorageProject(idProject, stprojectname, stprojectdisplayname, privileges, fdisablefetchacl, fautosyncacl, stlexiconname, connectorinfo) where idproject is the id of the project that need to be updated, stprojectname is the new name of the project to be updated, stprojectdisplayname is the new display name of the project to be updated, privileges is the StorageProjectPrivileges object that can be used to update the default privileges on the project, fdisablefetchacl can be used to disables fetching ACL flags, fautosyncacl can be used to auto sync the ACL flags, stlexiconname is used to update the lexicon for the project Creating a Sharepoint Project To create a Project with name stprojectname and display name stprojectdisplayname, IStorageProjectInfo projinfo = StorageHome.createSharepointArchiveStorageProject(auiOwner, sharepointservernode, stprojectname, stprojectdisplayname, iprojecttype, fallowversioning, privileges, fdisablefetchacl, fautosyncacl, stguid, fserverapi, fskiphidden, stlocaluser, stuserpassword, stlexiconname, connectorinfo) where auiowner is a user (instance of IArchiveUserInfo) that can be obtained using one of the methods explained earlier, sharepointservernode is the file server (instance of IMailServerInfo) where ZL s connector for a File server/sharepoint server/documentum server resides, iprojecttype is the integer value representing the type of project being created (valid values of project type are defined at com.zlti.zlservices.app.storage.istorageprojectinfo.type_*), fallowversioning is a boolean 63

65 File Archiving & Storage Related API value notifying if versioning of files inside this project is allowed or not, privileges is the instance of StorageProjectPrivileges which is used to set default privileges for the project which can be created as discussed above, fdisablefetchacl is a boolean value set to disable fetching ACL, fautosyncacl is a boolean value used to auto sync ACL flags, stguid is a string value which is needed to identify the sharepoint site, fserverapi is a boolean value needed to specify if the sharepoint project is using server side deployment, fskiphidden is a boolean value which skips any hidden files while crawling if this value is set to true, stlocaluser is the login user for sharepoint site when deployed at client side, stuserpassword is the login password for sharepoint site when deployed at client side, stlexiconname is used to specify lexicon that can be applied on this particular project Updating a Sharepoint Project StorageHome.updateSharepointStorageProject(idProject, stprojectname, stprojectdisplayname, privileges, fserverapi, fskiphidden, stsploginusername, stsploginpwd, fdisablefetchacl, fautosyncacl, stlexiconname, connectorinfo) where idproject is the id of the project that need to be updated, stprojectname is the new name of the project to be updated, stprojectdisplayname is the new display name of the project to be updated, privileges is the StorageProjectPrivileges object that can be used to update the default privileges on the project, fserverapi is a boolean value needed to specify if the sharepoint project is using server side deployment, fskiphidden is a boolean value which skips any hidden files while crawling if this value is set to true, stlocaluser is the login user for sharepoint site when deployed at client side, stuserpassword is the login password for sharepoint site when deployed at client side, fdisablefetchacl can be used to disables fetching ACL flags, fautosyncacl can be used to auto sync the ACL flags, stlexiconname is used to update the lexicon for the project Creating a Documentum Project To create a Project with name stprojectname and display name stprojectdisplayname, IStorageProjectInfo projinfo = StorageHome.createDocumentumArchiveStorageProject(auiOwner, fileservernode, stprojectname, stprojectdisplayname, iprojecttype, fallowversioning, privileges, fdisablefetchacl, fautosyncacl, dirspec, strepository, stusername, stpassword, stlexiconname, connectorinfo) where auiowner is a user (instance of IArchiveUserInfo) that can be obtained using one of the methods explained earlier, fileservernode is the file server (instance of IMailServerInfo) where ZL s connector for a File server/sharepoint server/documentum server resides, iprojecttype is the integer value representing the type of project being created (valid values of project type are defined at com.zlti.zlservices.app.storage.istorageprojectinfo.type_*), fallowversioning is a boolean value notifying if versioning of files inside this project is allowed or not, privileges is the instance of StorageProjectPrivileges which is used to set default privileges for the project which can be created as discussed above, fdisablefetchacl is a boolean value set to disable fetching ACL, fautosyncacl is a boolean value used to auto sync 64

66 File Archiving & Storage Related API ACL flags, dirspec is the instance of IDirectorySpec which contains the specification of directories that are included as well as excluded for archiving files, strepository is the documentum repository name, stlocaluser is the login user name, stuserpassword is the login user password, stlexiconname is used to specify lexicon that can be applied on this particular project Updating a Documentum Project StorageHome.updateDocumentumStorageProject(idProject, stprojectname, stprojectdisplayname, privileges, stsploginusername, stsploginpwd, stdcrepository, fdisablefetchacl, fautosyncacl, stlexiconname, connectorinfo) where idproject is the id of the project that need to be updated, stprojectname is the new name of the project to be updated, stprojectdisplayname is the new display name of the project to be updated, privileges is the StorageProjectPrivileges object that can be used to update the default privileges on the project, stlocaluser is the login user name, stuserpassword is the login user password, stdcrepository is the documentum repository name, fdisablefetchacl can be used to disables fetching ACL flags, fautosyncacl can be used to auto sync the ACL flags, stlexiconname is used to update the lexicon for the project Navigating through a Project s File Folders During a crawl process on the storage project, any new files found on the file system are archived by ZL according to the policy specified on the project. The archived files reside under the same folder hierarchy under the project as that of their original folder hierarchy on the file system except that the root path is replaced with the symbolic link of the particular directory specification. The top level (also referred to as root level folders) archived folders on ZL can be obtained on a specific project as follows, IStorageFolderInfo[] afolderinforoot = projectinfo.getrootfolders(); If the project is not yet archived by ZL, the folder hierarchy does not exist and the above API call will result in a null return. Each instance of the IStorageFolderInfo object represents an archived folder for a specific project and if the folders are nested deep, subsequent child folders of a given folder can be obtained as follows, IStorageFolderInfo[] afolderchild = folderroot.getchildfolders(); where folderroot is one of the root folders returned from the API call that returns an array of root level folders and afolderchild is a returned array of child folders. If there are no child folders for folderroot the call returns a null array. If the entire archived folder structure of project is desired, the getchildfolders() API needs to be called recursively over every child folder until the API returns null. The following is a sample code that recursively collects entire folder structure of a given project: IStorageFolderInfo[] afolderinforoot = projectinfo.getrootfolders(); 65

67 File Archiving & Storage Related API List<IStorageFolderInfo> listallfolders = new ArrayList<IStorageFolderInfo>(); if(afolderinforoot!= null){ for(istoragefolderinfo folderinfo : afolderinforoot){ addchildrecursively(folderinfo, listallfolders); void addchildrecursively(istoragefolderinfo folderinfo, List<IFolderInfo> list) { list.add(folderinfo); IStorageFolderInfo[] folderinfochild = folderinfo.getchildfolders(); if(folderinfochild!= null) { addchildrecursively(folderinfochild, list); If a parent folder of specific folder is desired it can be obtained on the child folder as follows, IStorageFolderInfo folderparent = folderchild.getparentfolder(); If the child folder used in the above API call is already a root level folder, the API call will result in a null return value for the parent folder Navigating through a Project Folder s Archived Files Once the folder information of a specific project is obtained using one of the APIs described in the previous section, the archived files contained in that particular folder can be obtained as follows, IStorageResultSet storageresutlset = folderinfo.getfolderitems( stsortfield, fascending); where IStorageResultSet is a result set of file objects contained in that particular folder, stsortfield is a String field on which this result set is sorted and fascending is a boolean value which indicates whether the sorting on the sort field will be in ascending or descending order. If the order desired is ascending, the value of this parameter should be true else false. 66

68 File Archiving & Storage Related API The values of valid sort fields supported by this API are from com.zlti.zlservices.app.storage.istoragefolderinfo.sort_*. If no sorting is desired, the value of this sort field should be passed as com.zlti.zlservices.app.storage.istoragefolderinfo.sort_none. The IStorageResultSet object offers three important APIs hasnext(), next(), and close() that are used to navigate through all the files that it represents. Follows code snippet walks through all the messages in a folder using the IStorageResultSet object on that folder, IStorageResultSet storageresutlset = folderinfo.getfolderitems( stsortfield, fascending); while(storageresultset.hasnext()) { IStorageItemVersion siversion = storageresultset.next(); // Custom code here to use IStorageItemVersion storageresultset.close(); The next() call on the IStorageResultSet object above returns an instance of the IStorageItemVersion object, which is the fundamental client object uniquely representing the current version of a file that is archived by the ZL server. 5.4 Searching for Files Files that are archived by the ZL server are indexed into search stores which can be searched for files Obtaining a Search Store These search stores for files can be obtained as follows, ISearchStore[] asearchstore = StorageSearchHome.getAllSearchStores(connectorInfo); where connectorinfo is the instance of IConnectorInfo Issuing a Search Query Once the search stores are obtained, queries can be issued on this search store to retrieve the files resulting from the search. Search query is an object with one or many search conditions that are combined with three operators, AND, OR, NOT. The following snippet of code illustrates how search conditions are created with conditions: ISearchQuery query = StorageSearchHome.createSearchQuery(); The above returns a search query which has no conditions inside it. Feeding this particular object to the server for search will result in an exception in the ZL server. 67

69 File Archiving & Storage Related API Creating a Search Condition To create a search condition on the name of file looking for test, ISearchCondition condbody = query.makeanyphrasecondition(storagesearchfields.field_name, "test"); To create a search condition on files whose sizes are in between 1KB (1024B) and 1MB (1024 * 1024B), ISearchCondition condsize = query.makerangecondition(storagesearchfields.field_message_size, 1024, 1024 * 1024); To create a search condition for files whose dates lie in the last one year, ISearchCondition conddate = query.makerangecondition(storagesearchfields.field_create_date, new Date(System.currentTimeMillis() - 365L*86400L*1000L), new Date()); To combine the previous three conditions (the file name condition, the date condition and the size condition) with an AND operator which means searching for all files that have the phrase test in their names and whose size lie between 1 KB and 1 MB and whose date happens to be in the last one year, ISearchCondition condcombined = query.combine(isearchquery.comb_opid_and, new ISearchCondition[] { condbody, condsize, conddate); To close the combined condition on the search query, query.close(condcombined); A search query object (ISearchQuery) is not a valid query to the ZL server until and unless it is closed before sending it to the ZL server. All the various fields of the files on which ISearchCondition can be obtained are from com.zlti.zlservices.app.storage.storagesearchfields.field_* Navigating through Files from the Search Result Once the search store and query have been constructed, files resulting for this query can be obtained as follows: IStorageSearchResultSet storagesearchresultset = StorageSearchHome.search(searchStore, srchquery, afieldvaluehistogram, connectorinfo); 68

70 File Archiving & Storage Related API where IStorageSearchResultSet is a result set of file objects. The IStorageSearchResultSet object offers three important APIs hasnext(), next() and close() that are used to navigate through all the messages that it represents. The following code snippet walks through all the files resulting from the search: IStorageSearchResultSet storagesearchresultset = StorageSearchHome.search(searchStore, srchquery, afieldvaluehistogram, connectorinfo); while(storagesearchresultset.hasnext()) { IStorageItemVersion siversion = storagesearchresultset.next(); // Custom code here to use IStorageItemVersion storagesearchresultset.close(); The next() call on the IStorageSearchResultSet object above returns an instance of the IStorageItemVersion object, which is the fundamental client object uniquely representing the current version of the file that is archived by the ZL server. 5.5 File handling Downloading a File Once the file object (IStorageItemVersion) is obtained, the actual file content can be downloaded in the form of standard java object InputStream as shown below, InputStream isfilecontent = siversion.getcontent(); where siversion is the instance of IStorageItemVersion object obtained from the ZL server Uploading a File Uploading a file to the ZLserver can be achieved by using the object IFileUpload. An instance of this IFileUpload can be obtained as shown below, IFileUpload fileupload = StorageHome.uploadMessage(idProject, strelativepath, stname, stmimetype, datefilelastmodified, datefilelastaccessed, imessagetype, stsourceinfo, stsourcemiscinfo, connectorinfo); where idproject is the identifier of the project to which this file is being uploaded, strelativepath is the relative path of this file under the project, datefilelastmodified and 69

71 File Archiving & Storage Related API datefilelastaccessed are the date attributes of the file, imessagetype is the type of the file and should be one of the valid ZL message types as defined in com.zlti.zlservices.app.mail.messagetype.file_*, stsourceinfo is a String value notifying the server of the source of the file which can be used for tracking as well as reporting purposes, stsourcemiscinfo is another String value to put any marker on the uploaded file which can be used for tracking and reporting on the ZL server, connectorinfo is the instance of the IConnectorInfo explained in the earlier section. Once the instance of IFileUpload is obtained, if the file level version attributes need to be set or if the file being uploaded is a particular version of the file, it can be done as follows, fileupload.setversioninfo(idversion, stversionlabel, mapversionmeta); where idversion is the integer that represents the identifier of the version being uploaded, stversionlabel is the String representing the label of the version and mapversionmeta is an instance of java.util.map interface, mapping a key (String) to a value (String) representing the metadata of the file. The actual message content can be uploaded by getting the TransactionOutputStream on the IFileUpload object as follows, TransactionOutputStream tos = fileupload.getuploadstream(); where tos is the instance of TransactionOutputStream which is a ZL client object extending Java OutputStream. The TransactionOutputStream provides a special service of aborting the stream (transaction) if needed. If an error is detected on writing the content to this TransactionOutputStream, the stream can be aborted which prevents the transaction from uploading incomplete data to the ZL server as follows, tos.abort(); Once the TransactionOutputStream has been closed and the content has been successfully uploaded, ZL server acknowledges the accepted content/file with a unique identifier (string id) which can be used to track the file on the ZL server from then on. This received mail identifier can be obtained on the IFileUpload as follows, String strmid = fileupload.getreceivedmailid(); The above method for getting the received mail identifier should only be called after a successful file content upload (i.e. after closing the TransactionOutputStream), otherwise this API call results in an exception. The following snippet of code illustrates the mechanism of uploading a message to the ZL server: /* 70

72 File Archiving & Storage Related API IFileUpload fileupload = StorageHome.uploadMessage(idProject,stRelativePath,stName,s tmimetype,datefilelastmodified,datefilelastaccessed,imessag etype,stsourceinfo,stsourcemiscinfo,connectorinfo); fileupload.setversioninfo(idversion,stversionlabel,mapversi onmeta); TransactionOutputStream tos = fileupload.getuploadstream(); // C:\\test.txt contains the content of the file to be uploaded InputStream isfilecontent = new FileInputStream(new File( C:\\test.txt ); try { // custom code stream isfilecontent to tos ; // tos.close(); catch (Exception e){ tos.abort(); throw e; finally { isfilecontent.close(); String streceivedmailid = fileupload.getreceivedmailid(); */ 71

73 Case Management Related API 6 Case Management Related API Note The following components of ZLServices API Kit have to be considered experimental features, even if they are part of a "stable" release or an official version. If you use any of these features then you have to be aware that they may be incomplete in their implementation, have known issues, or their design and programming interface is subject to change in the future, so it may require you to adapt your experiment code to the changing interface when upgrading to a future release of ZLServices API Kit. Figure 9 Case Management Object Schema 72