SAPERION Classic Connector

Copyright © SAPERION AG

Disclaimer

The content of this manual, including all images, tables, and drawings are the intellectual property of SAPERION AG.All rights are reserved. Altering or deleting copyright notes, distinguishing marks and/or control numbers, or drawings isprohibited.

SAPERION AG grants the use of the contents for contractual purposes only. The contents of this manual are subjectto changes without requiring SAPERION AG to provide prior notice. The users of the manual are obligated to informthemselves, at regular intervals, about the availability of modified versions or other details concerning the offered productsand services in the Internet at www.saperion.com and to take such information into consideration during use.

All devices and program names and other products from SAPERION, as well as the corresponding logos used in thismanual are trademarks or registered trademarks of SAPERION AG in Germany and other countries worldwide. All otherproduct and service names are trademarks of the respective companies.

The information in this manual is provided by SAPERION AG and its affiliated group companies ("SAPERION Group").The SAPERION Group assumes no liability for errors or omissions in this manual. The only warranties for SAPERIONGroup products and services are those that are set forth in the express warranty statements accompanying such productsand services. Nothing in this manual should be construed as constituting an additional liability.

Copyright © SAPERION AG

SAPERION AGSteinplatz 2D-10623 Berlin

Sales 781.899.1228Fax: 781.899.1244Email: usa.sales@SAPERION.comWeb: http://www.SAPERION.com

Table of Contents

1 Introduction ......................................................................................................... 2

2 The Classic Connector ........................................................................................ 2

3 Classic Connector Project ................................................................................... 2

4 General Rules for HQL ....................................................................................... 3

5 Examples .............................................................................................................. 3

5.1 Login/ Logoff ................................................................................................... 3

5.2 Creating Documents ....................................................................................... 4

5.3 Searching for Documents ............................................................................... 5

5.4 Parallel Search in Two Database Defitions ................................................... 6

5.5 Search with "In-clause" ................................................................................... 6

5.6 Searching for Deleted Documents ................................................................. 6

5.7 Updating Documents ...................................................................................... 7

5.7.1 Example: Attaching a File ............................................................................... 7

5.7.2 Example: Modifying a Field in the Document Metadata ............................... 7

5.8 Managing and Using a Connection Pool ....................................................... 8

6 Workflow Examples ............................................................................................. 9

6.1 Logging on to a Connector ............................................................................. 9

6.2 Starting a Business Case ................................................................................ 9

6.3 Defining a User for a Task .............................................................................. 10

6.4 Declining All Tasks .......................................................................................... 10

2

SAPERION Classic Connector

1 Introduction

This documentation is intended for developers and offers some programming examples of the

SAPERION Classic Connector including different operations via the API.

You can find a complete list of the classes and methods in the Javadocs of the Classic Connector supplied

in the SAPERION documentation portal under the following link:

Javadocs Classic Connector

2 The Classic Connector

The Classic Connector was developed for simple communication with the SAPERION backend system,

it supports methods for searching, creating, editing, and reading of documents. In this context the

connector runs on a document-centered basis.

The following functions are made available by the Classic Connector:

+ Logon / logoff with the SAPERION backend

+ Saving and modifying documents including metadata

+ Document search and query using metadata and full text in the database

+ Reading documents including metadata

+ Versioning documents and retrieving the version history

+ Saving and modifying folders

+ Access control using access control lists

+ Event control

+ Workflow

+ User administration

3 Classic Connector Project

In order to begin a project with the Classic Connector, it is necessary to integrate the following files,

located in the directories listed, into the development environment.

+ <SAPERION installation directory>/scr-classicconnector/lib

+ <SAPERION installation directory>/scr-classicconnector/config

In the following example the individual steps are listed that are required in Eclipse in order to create a

Classic Connector project.

4 General Rules for HQL 3

1. Start Eclipse.

2. Create a new Java project.

3. Create the directories "lib", "logs" and "config" in the project.

4. Copy all files from "<SAPERION installation directory>/scr-classicconnector/lib" into the "lib"-

directory you created in the new project.

5. Add the directory libraries to the build path.

6. Copy all the files from "<SAPERION installation directory>/scr-classicconnector/config to the

"config"-directory you created in the new project.

7. To create a log, customize the file "log4j.properties" in the "config"-directory. Enter the path to the

"logs"-directory you created in the new project.

4 General Rules for HQL

When programming the Classic Connector you must bear certain rules in mind:

+ Use HQL queries with aliases.

select d.NAME

from defaultexample d

where d.SYSROWID='...'

+ Use upper case letters for all fields in HQL queries.

d.SCOMMENT

d.NAME

+ Use lower case letters for all DDC names in HQL

defaultexample d

5 Examples

5.1 Login/ Logoff

For a login via SaClassicConnector you have first to instantiate an implementation of this interface, e.g.

by means of a path information to the "saperion.properties".

SaClassicConnector connector = new SaClassicConnectorImpl(

“c:/saperion/scr/config/saperion.properties”);

Alternatively this implementation can also be instantiated with an empty constructor if the corresponding

directory information is given to the JVM.

Example under Eclipse

Eclipse > Runtime Configurations > (x) = arguments > VM arguments >"

-Dsaperion.config=c:/saperion/scr/config/"

4

The authentication at the Classic Connector is carried out by means of password and user role resp.

license type (in multiclient systems the client has to be defined as well).

Following user roles resp. license types are available (see also "com.saperion.constants.SaConstants):

User roles/ License types

Code User Role

1 Index

2 Query

3 Universal/ administrator

4 Web query

7 Web index

12 Workflow

13 Scan

14 Scan (Highend)

15 API query

16 API index

17 API scan

20 Administrator

29 Web workflow

Example login as universal/ administrator

The login is achieved by the method "logon":

connector.logon("user name", "password", 3, "client");

Example check of the connection

With the following example the comnnection can be checked:

System.out.println(connector.isAlive() ? "Connection still alive."

: "Connection has died.")

Example logoff of the user

Furthermore users can be logged off by means of the method "logoff":

connector.logoff();

5.2 Creating Documents

When creating documents, metadata have to be specified depending on the corresponding document

definition table. Without mandatory metadata fields it is not possible to create documents.

5 Examples 5

In the following example a document is created in the database defintion "example71".

Example

//Metadata

HashMap<String, Object> metadata = new HashMap<String, Object>();

metadata.put("EX7_DOCNAME", "Example Document Name");

metadata.put("EX7_COMMENT", "Example Document description");

metadata.put("EX7_ARCDATE", new Date());

metadata.put("EX7_LANGUAGE", "English");

//Creating a document on SaClassicConnector instance connector

connector.createDocument(new DocumentInfo(SADEFINITION, metadata,

new ContentStream[] { new ContentStream(new FileInputStream(

"<path>/file.doc"), "File description") }, "Comment"));

5.3 Searching for Documents

With the method "searchHQL" documents can be searched by means of HQL syntax. This way, all

documents of a definition can be queried with the following HQL string:

select d from <definition name> d

+ If only specific information are needed the query is as follows:

Example

select d.<field name> from <definition name> d where d.<another field name> like '%<STRING>%'

+ Search for the last archiving of documents with "ECM" in its name:

Example

String DATEFIELD = "EX7_ARCDATE";

SaQueryInfo info = new SaQueryInfo("select d."+DATEFIELD+" from example71 d

where d.EX7_DOCNAME like '%ECM%'"));

List<SaDocumentInfo> docs = connector.searchHQL(info);

Calendar latestcal = null;

Calendar calendar = null;

for (SaDocumentInfo doc : docs) {

SaValue value = doc.getValue(DATEFIELD).getValues()[0];

if (value.getValueType() == SaConstants.FT_DATE) {

calendar = value.getCalendarValue();

if ((latestcal == null) || (calendar.compareTo(latestcal) > 0))

latestcal = calendar;}}

System.out.println("The latest ECM file archive was on "

+ new SimpleDateFormat("yyyy-MM-dd").format(latestcal

.getTime()));

6

5.4 Parallel Search in Two Database Defitions

The following example illustrates a parallel search for documents in two different database definitions.

The document has the same value in the field "EX7_DOCNAME" both in the definition "example7" and

in "example71".

Example

String hql_search_string = "select d from EXAMPLEV7 d, EXAMPLE71 e where

d.EX7_DOCNAME = e.EX7_DOCNAME";

List<SaDocumentInfo> results = connector.searchHQL(new SaQueryInfo(

hql_search_string));

for (SaDocumentInfo doc : results) {

System.out.println(doc.getValue("EX7_DOCNAME").getStringValue()

+ " is in both definitions – possible duplicate");}

5.5 Search with "In-clause"

By means of a parameter list a specific sub-quantity of documents can be queried. In this example

parameters are defined in "namelists".

Example

String hql_search_string = "select d from EXAMPLE71 d where

d.EX7_DOCNAME in (:names) ";

SaQueryInfo query = new SaQueryInfo(hql_search_string);

Collection<String> namelist = new ArrayList<String>();

namelist.add("Example Document Name1");

namelist.add("Example Document Name2");

//etc.

query.setParameterList("names", namelist);

List<SaDocumentInfo> results = connector.searchHQL(query);

5.6 Searching for Deleted Documents

The basic condition for a search for deleted documents is that in the concerning database definition

(DDC) the option " Enable recycle bin and indexer task (SYSINDEXSTATE)" is selected. Doing so the

document will only be temporarily and not directly removed from the table (it is definitely deleted at

the second time). The document has then the SYSINDEXSTATE value 65002. At a regular request all

documents with SYSINDEXSTATE 65002 are ignored.

With the following workaround it is possible to search for deleted documents:

Example

5 Examples 7

String sql = "select d from EXAMPLE71 d where d.SYSINDEXSTATE=65002";

SaQueryInfo query;

query = new SaQueryInfo(sql);

//Set new upper limit for SYSINDEXSTATE:

query.setInteger("sysindexstate", 65003);

List<SaDocumentInfo> results = connector.searchHQL(query);

System.out.println("Found " + results.size() + " deleted documents.");

! The here mentioned workaround is not supported from SAPERION version 7.5.1 on. Starting from

this version, the Classic Connector API will be enhanced for this purpose.

5.7 Updating Documents

The document update in SAPERION is parameterized by different integer values which are:

Update parameters

Integer Value Description

-2 The existing document content will be deleted so that an empty document structure is left.

-1 The existing document content will be deleted and a defined content will be added as first element.

0 The specified content will be added as last element.

>0 The element with the specified number will be replaced by the defined content so that the count of elements is not

changed.

Example: Attaching a File

//Create new content stream

File file = new File("D:/<any path>/content.txt");

String filename = file.getName();

InputStream newFile = new FileInputStream(file);

//0 for append

ContentStream newcs = new ContentStream(newFile, filename, 0);

//Create new array

ContentStream[] csarray = new ContentStream[]{newcs};

//Update document, hdoc 872… is known (e.g. by query)

connector.updateDocument(new UpdateDocumentInfo(“definition”,

"872CBA9FF46541420F00010000003200000000000000",

new HashMap<String, Object>(), csarray, "comment"));

Example: Modifying a Field in the Document Metadata

If only metadata should be modified the ContentStream[] is set to null when updating:

//Create metadata field

8

Map<String, Object> changedfields = new HashMap<String, Object>();

changedfields.put("EX7_ARCDATE", new Date());

//Nur Metadaten updaten (csarray ist hier null)

connector.updateDocument(new UpdateDocumentInfo(SADEFINITION,

"872CBA9FF46541420F00010000003200000000000000", changedfields, null, "updated date"));

5.8 Managing and Using a Connection Pool

The administration of a connection pool is achieved by the "ConnectionPoolUtil" class. The underlying

pool is based on the "GenericKeyedObjectPool" and can be configured accordingly.

See also:

In order to be able to create a connection to Java Core Server you have first to set the path information

as JVM runtime parameter in the configuration file "saperion.properties".

Example under Eclipse

Eclipse > Runtime Configurations > (x) = arguments > VM arguments : > "

-Dsaperion.config=c:/saperion/scr/config/ "

A minimal configuration and the instantiation of the Classic Connector could be as follows:

Example

Properties poolConfiguration = new Properties() ;

//Set minimal properties:

poolConfiguration.setProperty("poolUtil.test.on.return", "false");

poolConfiguration.setProperty("poolUtil.test.while.idle", "false");

poolConfiguration.setProperty("pool.min.idle", "0");

poolConfiguration.setProperty("pool.max.idle", "8");

poolConfiguration.setProperty("pool.max.active", "10");

poolConfiguration.setProperty("pool.max.total", "-1");

poolConfiguration.setProperty("pool.max.wait", "-1");

poolConfiguration.setProperty("pool.idle.test.count", "3");

poolConfiguration.setProperty("pool.exhausted.action", "1");

poolConfiguration.setProperty("pool.time.between.eviction","120000");

poolConfiguration.setProperty("pool.idle.test.count","3");

poolConfiguration.setProperty("pool.idle.min.evictable.time","120000");

UsernamePasswordKey key = new

usernamePasswordKey(“login”,”password”,3,"");

//leerer Pfad zu saperion.properties

cpu.initialize(poolConfiguration, "");

PooledSession session = (PooledSession) cpu.borrowObject(key);

SaClassicConnector connector = session.connection();

6 Workflow Examples 9

After the hand-over of the instance operations can be executed regularly:

System.out.println(connector.isAlive() ? "Connection still alive."

: "Connection has died.");

Finally, the resource is returned to the pool for further use:

cpu.returnObject(key, session);

6 Workflow Examples

The SaWFConnector allows access to the SAPERION workflow functions. It can be either instantiated

via the SAPERION Classic Connector or created by itself.

SaWFConnector wfc = connector.getWorkflowConnector();

or

SaWFConnector wfc = new SaWFConnectorImpl();

6.1 Logging on to a Connector

For a login to the SaWFConnector the method "logon" is used. The authentication parameters are

identical to the parameters of the Classic Connector described above.

Example

wfc.logon("login", "password", 3, "client");

6.2 Starting a Business Case

As soon as the SaWFConnector instance has been created, business cases can be started by means of

the method "executeStartProcess". The user name is here the user's short name or login name.

Example

ActorInfo nextActor = new ActorInfoImpl("User name");

TaskInfo info = wfc.executeStartProcess("approval", nextActor,

"Test start", "" + wfc.getUserId());

10

6.3 Defining a User for a Task

A business case can be assigned to specific users. The following possibilities are available:

SaWFTask task = wfc.getTask("sysrowid");

+ The user who is currently logged on to the Classic Connector receives the task:

task.executeAssignToMe();

+ A specified user receives the task:

task.executeDelegate(new ActorInfoImpl("User name"));

+ The task is assigned to a new owner:

task.executeChangeOwner(new ActorInfoImpl("User name"));

6.4 Declining All Tasks

It is to decline all business case tasks and to assigned them to a new owner:

Example

SaWFConnector wfc = connector.getWorkflowConnector();

List<BoxDefinition> boxdefs = wfc.getBoxDefinitions();

for (BoxDefinition def : boxdefs) {

List<TaskInfo> taskinfos = wfc.getTaskList(

new int[] { def.getBoxID() }, "");

for (TaskInfo info : taskinfos) {

Map<String, SaPropertyValue> propmap = info.getSysFields();

SaWFTask task = wfc.getTask(propmap.get("SYSROWID")

.getStringValue());

task.setComment("Denied Workflow because...");

task.executeReject(new ActorInfoImpl("User name"));}}