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 is
prohibited.
SAPERION AG grants the use of the contents for contractual purposes only. The contents of this manual are subject
to changes without requiring SAPERION AG to provide prior notice. The users of the manual are obligated to inform
themselves, at regular intervals, about the availability of modified versions or other details concerning the offered products
and 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 this
manual are trademarks or registered trademarks of SAPERION AG in Germany and other countries worldwide. All other
product 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 SAPERION
Group products and services are those that are set forth in the express warranty statements accompanying such products
and services. Nothing in this manual should be construed as constituting an additional liability.
Copyright SAPERION AG
SAPERION AG
Steinplatz 2
D-10623 Berlin
Sales
Fax:
Email:
Web:

781.899.1228
781.899.1244
usa.sales@SAPERION.com
http://www.SAPERION.com

Table of Contents
1
Introduction .........................................................................................................
2
The Classic Connector ........................................................................................
3
Classic Connector Project ...................................................................................
4 General Rules for HQL .......................................................................................
5
Examples ..............................................................................................................
5.1
Login/ Logoff ...................................................................................................
5.2
Creating Documents .......................................................................................
5.3
Searching for Documents ...............................................................................
5.4
Parallel Search in Two Database Defitions ...................................................
5.5
Search with "In-clause" ...................................................................................
5.6
Searching for Deleted Documents .................................................................
5.7
Updating Documents ......................................................................................
5.7.1 Example: Attaching a File ...............................................................................
5.7.2 Example: Modifying a Field in the Document Metadata ...............................
5.8
Managing and Using a Connection Pool .......................................................
6 Workflow Examples .............................................................................................
6.1
Logging on to a Connector .............................................................................
6.2
Starting a Business Case ................................................................................
6.3
Defining a User for a Task ..............................................................................
6.4
Declining All Tasks ..........................................................................................

2
2
2
3
3
3
4
5
6
6
6
7
7
7
8
9
9
9
10
10

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

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

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.

General Rules for HQL

1.
2.
3.
4.
5.
6.
7.

Start Eclipse.
Create a new Java project.
Create the directories "lib", "logs" and "config" in the project.
Copy all files from "<SAPERION installation directory>/scr-classicconnector/lib" into the "lib"directory you created in the new project.
Add the directory libraries to the build path.
Copy all the files from "<SAPERION installation directory>/scr-classicconnector/config to the
"config"-directory you created in the new project.
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.

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

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 >
-Dsaperion.config=c:/saperion/scr/config/"

(x)

arguments

>

VM

arguments

>"

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

Index

Query

Universal/ administrator

Web query

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.

Examples
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

Examples

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.

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 >
-Dsaperion.config=c:/saperion/scr/config/ "

(x)

arguments

>

VM

arguments

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();

>

"

Workflow Examples
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);

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"));}}