DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

EXT: GSA Socket¶

Author:	Kasper Skårhøj
Created:	2002-11-01T00:32:00
Changed by:	Rainer Kuhn
Changed:	2009-11-27T16:56:46.560000000
Author:	Rainer Kuhn
Email:	t3extensions@punkt.de
Info 3:
Info 4:

EXT: GSA Socket¶

Extension Key: pt_gsasocket

Manual revised for pt_gsasocket version 1.0.0, 2009-11-27

Extension development sponsored by punkt.de GmbH ( `http://punkt.de/ <http://punkt.de/>`_ )

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

- a GNU/GPL CMS/Framework available from www.typo3.com

Table of Contents¶

EXT: GSA Socket 1

Introduction 1

What does it do? 1

Screenshots 2

Administration 3

Installation requirements 3

Basic considerations 3

Running GSA Socket with the GSA Standalone Database 3

Running GSA Socket with the GSA tables imported to your TYPO3 database 3

Running GSA Socket with the ERP system 3

Installation of the TYPO3 extensions 4

Configuration 4

Known problems 5

To-Do list 5

Changelog 6

Introduction¶

What does it do?¶

This extension provides the access to the additional data layer for GSA Shop and all extensions of the 'General Shop Applications' (GSA) category, the GSA extension family (pt_gsa* ). This GSA data layer has been created compatible to the German enterprise resource planning system (ERP) “GS Auftrag Professional” to allow the integration of the GSA extensions with this ERP - but the GSA extensions do not necessarily need the ERP system and are able to be run as a TYPO3 standalone version.

Furthermore this extension provides additional functionality for developers to access data and files of the above mentioned ERP system. These are not needed if you run the 'General Shop Applications' extensions as a standalone TYPO3 package without the ERP system.

Legal notice / Disclaimer¶

“GS Auftrag”, Windows and all other third-party product names, trademarks or registered trademarksmentioned in this manual are the property of their respective owners.

Screenshots¶

The screenshot shows some of the configuration options of pt_gsasocket in TYPO3's extension manager. The extension has to be configured here right after installation to enable access to the GSA data layer.

Administration¶

Installation requirements¶

These are the current requirements to install and run GSA Socket:

PHP 5.1 or higher
TYPO3 4.1 or higher with the extension 'pt_tools' installed
MySQL database server with an appropriate GSA database [ GSAMINIDB (ext. pt_gsaminidb) or GSMAND<n> ] or with the required GSA database tables (ext. pt_gsaminidb version 0.0.4 or above) imported into your TYPO3 database, see below.

Basic considerations¶

Since the installation of GSA Socket and the 'General Shop Applications' (GSA) bunch of extensions is not trivial this should be done by an administrator or someone with the appropriate technical background!

First you have to decide which underlying data layer you want to use for your GSA extensions: You can optionally use

The GSA standalone database: a minimal required database delivered with the extension pt_gsaminidb, see below.

The GSA database tables imported to your TYPO3 database: the required tables are delivered with the extension pt_gsaminidb. This is a workaround for TYPO3 users who do not have the privileges to create an additional database on their database server, but it is not a complete TYPO3 integration, details see below.

The database of an existing installation of the German enterprise resource planning (ERP) system “GS AUFTRAG Professional”. This option is restricted to selected elements of the ERP database, requires a special ERP software version and some manual database modifications, see below.You'll find more information about the current version of the ERP system at the German web page http://www2.sage.de/sb/prodloes /warenwirtschaft/gs_auftrag_professional/gs_auftrag_professional.a sp .

IMPORTANT :Please note if you're running an additional (non TYPO3) GSA database: Independently of your GSA database source choice, you should be aware not to use the same database user name for the GSA database like the one you already use for your TYPO3 database, since this may lead to access problems under certain circumstances.

Running GSA Socket with the GSA Standalone Database¶

If you decide to run GSA Socket with the GSA Standalone Database (extension key: pt_gsaminidb), please install the separate database delivered as an SQL file (“GSAMINIDB.sql”) with the extension pt_gsaminidb at your MySQL database server (please refer to this extension's manual for details). The installation will create the MySQL database “ GSAMINIDB ”.

Running GSA Socket with the GSA tables imported to your TYPO3 database¶

If you decide to run GSA Socket with the GSA tables imported to your TYPO3 database, use the appropriate SQL importer script (“tx_ptgsaminidb_tables.sql”) delivered with the extension pt_gsaminidb and refer to that extension's manual for details. The import will create the GSA database tables, all prefixed with “tx_ptgsaminidb_*” and followed with the original GSA table name, most of them in German uppercase letters.

IMPORTANT : This way of using the GSA database tables is:underline:not recommended . It isjust a workaround to use only one database for TYPO3 users who do not have the privileges to create an additional database on their database server. Due to massive differences in the database design of the GSA database and the TYPO3 database this is:underline:not a complete TYPO3 integration of the GSA tables (e.g. neither a proper TYPO3 database/SQL integration nor a TCA integration), resulting in some problems and risks. Please refer to the manual of the extension pt_gsaminidb for details.

Running GSA Socket with the ERP system¶

If you want to use the GSA extensions in combination with the ERP system, please note that only certain parts of the database are used by the GSA extensions. This may result in not all features of the ERP system being supported in combination with the GSA extensions.

Furthermore the GSA extensions require the database from version 2.7.x up to 2.8.11.1 of the ERP system (the 2.8.x series is also called “GS- AUFTRAG 2007”). Modifications for the newest product version “GS- AUFTRAG 2008 Professional” have not been implemented yet.

If you decide to run GSA Socket with one of the mentioned versions of the ERP system, you have to choose MYSQL as database server when installing “GS-AUFTRAG”. The installation will create a MySQL database named “ GSMAND<n> ”. You have to extend this database for usage with the GSA extensions by importing the SQL scripts provided in this extension (pt_gsasocket/res/sql directory) on your MySQL console:

import the structure of the additional table “px_DTABUCH” using the SQL script px_DTABUCH.sql delivered with this extension (pt_gsasocket/res/sql/px_DTABUCH.sql)
import the structure and data of the additional table “px_laender” using the SQL script px_laender.sql delivered with this extension (pt_gsasocket/res/sql/px_laender.sql): Do not use any other version of this table since this leads to problems with the country codes!

It is highly recommended to run extensive tests with the GSA extensions running in combination with the ERP system before switching to a production system. In particular you should check if all features of the ERP system required for your individual use case are working correctly with database records created or modified with the GSA extensions. To check the database modifications of the GSA extensions, you can activate an appropriate logging option in the GSA Socket's configuration (see below).

Installation of the TYPO3 extensions¶

After choosing and creating your GSA database you have to install the extension pt_tools (dependency) and the extension pt_gsasocket itself. Right after the installation you can configure the extension in TYPO3's extension manager as described in chapter “Configuration”.

Configuration¶

All configuration options for the extensions have to be set in TYPO3's extension manager. Here you have to configure the underlying GSA database, the used charset, logging and optionally an ERP server directory to use.

If you've decided to run GSA Socket with the GSA Standalone Database or with the ERP system, you have to leave the first checkbox for the option “useGsaTablesInTypo3Database” unchecked and you have to fill out all “Additional GSA DB” fields (dbGSAhost, dbGSAname, dbGSAuser, dbGSApwd). But if you've chosen to import the GSA tables into your TYPO3 database, the mentioned “Additional GSA DB” entries are not required, but you have to check the first checkbox for the option “useGsaTablesInTypo3Database”

Please refer to the following table for all configuration options:

Use GSA tables in TYPO3 database¶

a

Use GSA tables in TYPO3 database

b

[useGsaTablesInTypo3Database]

Check this box if you want to use the GSA database tables within the¶

a

Check this box if you want to use the GSA database tables within the TYPO3 database instead of using an additional GSA database (you can do this by importing the SQL script tx_ptgsaminidb_tables.sql of the extension pt_gsaminidb, please refer to that extension's manual for details).

Default: 0

Additional GSA DB - host name¶

a

Additional GSA DB - host name

b

[dbGSAhost]

The name of the database host where the additional GSA database is¶

a

The name of the database host where the additional GSA database is located. This option is not required if you've decided not to use an additional GSA database by checking the above option "useGsaTablesInTypo3Database".

Default: localhost

Additional GSA DB - database name¶

a

Additional GSA DB - database name

b

[dbGSAname]

The database name of the additional GSA database. Please refer to the¶

a

The database name of the additional GSA database. Please refer to the extension manual for details on how to retrieve an appropriate database. This option is not required if you've decided not to use an additional GSA database by checking the above option "useGsaTablesInTypo3Database".

Default: GSAMINIDB

Additional GSA DB - user name¶

a

Additional GSA DB - user name

b

[dbGSAuser]

The name of the user allowed to use the additional GSA database. This¶

a

The name of the user allowed to use the additional GSA database. This option is not required if you've decided not to use an additional GSA database by checking the above option "useGsaTablesInTypo3Database".

Default: GSMandantUser

Additional GSA DB - password¶

a

Additional GSA DB - password

b

[dbGSApwd]

The password of the user allowed to use the additional GSA database.¶

a

The password of the user allowed to use the additional GSA database. This option is not required if you've decided not to use an additional GSA database by checking the above option "useGsaTablesInTypo3Database".

Default:

Additional GSA DB - initialization¶

a

Additional GSA DB - initialization

b

[dbGSAsetDBinit]

Individual SQL initialization command for the additional GSA database¶

a

Individual SQL initialization command for the additional GSA database (to send to database right after connecting), e.g. "SET NAMES <charset>". This option is ignored if you've decided not to use an additional GSA database by checking the above option "useGsaTablesInTypo3Database", the default $TYPO3_CONF_VARS['SYS']['setDBinit'] is used in this case.

Default:

Charset conversion of GSA data¶

a

Charset conversion of GSA data

b

[enableGsaCharsetConv]

Check this box if you want the GSA database string data to be¶

a

Check this box if you want the GSA database string data to be converted to another charset encoding used by the website. The used charset encoding of your GSA database should be configured at the following option "gsaCharset" (TYPO3's website charset is retrieved internally).

Default: 0

Charset encoding used by GSA-DB¶

a

Charset encoding used by GSA-DB

b

[gsaCharset]

Charset encoding used by the underlying GSA database. This setting has¶

a

Charset encoding used by the underlying GSA database. This setting has no effect if enableGsaCharsetConv is set to 0 (not checked).

Default: ISO-8859-1

GSA database modification logging¶

a

GSA database modification logging

b

[logEnabled]

Check this box if you want to enable the logging for all database¶

a

Check this box if you want to enable the logging for all database modifying SQL queries (INSERT, UPDATE, DELETE) on the GSA database (SELECT will _not_ be logged!). IMPORTANT: If enabled, the config values logDirPath, logAdminEmail and logHostName (see below) have to be set, too.

Default: 0

Log output directory¶

a

Log output directory

b

[logDirPath]

[Notice: This entry is needed only if the config value logEnabled (see¶

a

[Notice: This entry is needed only if the config value logEnabled (see above) is checked.] Absolute path to the server directory for generated logs (Notice: don't forget the prefacing and closing slashes "/"!). If not set, no log is written.

Default:

Log error email admin address¶

a

Log error email admin address

b

[logAdminEmail]

[Notice: This entry is needed only if the config value logEnabled (see¶

a

[Notice: This entry is needed only if the config value logEnabled (see above) is checked.] Email address for system messages on logging errors.

Default:

Log error email host name¶

a

Log error email host name

b

[logHostName]

[Notice: This entry is needed only if the config value logEnabled (see¶

a

[Notice: This entry is needed only if the config value logEnabled (see above) is checked.] Name of the host where this extension is used. This name is used for identification of the originating host in system emails sent on logging errors.

Default:

"GS Auftrag" server dir (optional)¶

a

"GS Auftrag" server dir (optional)

b

[pathGSAserverDir]

This setting is required only if you want to run the GSA extensions¶

a

This setting is required only if you want to run the GSA extensions with the "GS Auftrag" ERP system and need to retrieve data from the ERP files: In this case the directory path to the server directory where "GS Auftrag" stores its internal data for the currently used "Mandant"-user has to be set here (absolute server path, don't forget the prefacing and closing slashes "/").

Default: /gs/00001/

Known problems¶

None.

To-Do list¶

Currently nothing.

Changelog¶

((generated))¶

v1.0.0:¶

adapted extension dependencies/suggestions and manual

v0.3.0:¶

added the possibility to handle GSA database tables imported into an existing TYPO3 database for users who do not have have the privileges to create an additional database on their database server (see ext. pt_gsaminidb version 0.0.4 or above):
- new config option "useGsaTablesInTypo3Database" in pt_gsasocket's extension manager configuration
- new method getTableName() in tx_ptgsasocket_gsaDbAccessor to retrieve correct table names depending on this config( IMPORTANT : to be compatible with the new config option, from now on this method has to be used by all other GSA based extensions when accessing GSA database table names!)
- internal adaptions in the classes tx_ptgsasocket_gsaConnector and tx_ptgsasocket_gsaDbAccessor
added the possibility of using an individual SQL initialization command for the additional GSA database via the new config option "dbGSAsetDBinit" in pt_gsasocket's extension manager configuration
tx_ptgsasocket_gsaDbAccessor: added redeclared method SELECTquery(), added query tracing to all *query() methods for debugging
raised dependency for library extension pt_tools to v0.4.1, set vextension state to 'stable'
revised this manual for imported GSA database tables and added database user name problem notice to “Basic considerations”

v0.2.3:¶

improvement of site charset handling: removed "siteCharset" config option ("Charset encoding used by TYPO3") from Extension Manager, TYPO3 site charset retrieved internally now, appropriate revision of tx_ptgsasocket_gsaDbAccessor (constructor & properties)
raised pt_tools dependency to version 0.3.0

v0.2.2:¶

revision of this manual

v0.2.1:¶

changed configuration defaults for “dbGSAname”/“dbGSAhost” and updated this manual for usage combined with ext. pt_gsaminidb
revision of tx_ptgsasocket_gsaDbAccessor: extended updateNextNumber() and incrementNumberValue() to work with empty “NUMMERN” database table, removed obsolete updateNumberValue(), changed “private” declarations to “protected”

v0.2.0:¶

initial TER version (all versions before have not been published)

EXT: GSA Socket - 6