Difference between revisions of "Seon Core event scripts"

From Seon
Jump to: navigation, search
m
(end receive script)
 
(54 intermediate revisions by the same user not shown)
Line 2: Line 2:
  
 
The scripts are defined via web interface. This configuration is stored in the database, which will be read by every binary on startup and on every configuration reload. If a script is unavailable or not runnable (i.e. execute permissions are missing, user has no read permissions etc.), the script will not be started.
 
The scripts are defined via web interface. This configuration is stored in the database, which will be read by every binary on startup and on every configuration reload. If a script is unavailable or not runnable (i.e. execute permissions are missing, user has no read permissions etc.), the script will not be started.
 +
 +
All scripts, except of the start receive script, run in the background and don't influence active Seon transfers during their execution.
 +
 +
The following virtual filenames are reserved and therefor no "normal" script will be run on these files (send, receive, xERP & block):
 +
*<code>ODETTE_CERTIFICATE_REQUEST</code>: OFTP2 automatic certificate exchange request
 +
*<code>ODETTE_CERTIFICATE_DELIVER</code>: OFTP2 automatic certificate exchange delivery
 +
*<code>ODETTE_CRL_REQUEST</code>: OFTP2 automatic certificate revocation list request
 +
*<code>ODETTE_CRL_DELIVER</code>: OFTP2 automatic certificate revocation list delivery
 +
*<code>SEON-UPDATE</code>: Seon update package
  
 
== start session script ==
 
== start session script ==
Line 13: Line 22:
 
Will be started at the end of an OFTP session after receiving an ESID („end session ID“).  
 
Will be started at the end of an OFTP session after receiving an ESID („end session ID“).  
  
Parameters:  
+
Parameters:
 
*1. partner shortname  
 
*1. partner shortname  
 
*2. partner index value  
 
*2. partner index value  
  
 
== start receive script ==
 
== start receive script ==
Will be started at the beginning of an OFTP file transfer from partner to local site after handshaking SFIDs.  
+
Will be started at the beginning of an OFTP file transfer from partner to local site after handshaking SFIDs.
 +
'''This script is the only event script which will be started INSIDE the OFTP protocol state machine in order to let a file be received or not!''' For this feature, the returncode of the event script is used to decline the receipt of a file and to create an SFNA error message (if returncode of script is not equal to zero) or to accept the file, producing an SFPA message.
  
 
Parameters:  
 
Parameters:  
Line 29: Line 39:
 
*7. SFID destination  
 
*7. SFID destination  
 
*8. SFID originator  
 
*8. SFID originator  
*9. [optional: OFTPv2 file description]  
+
*9. [optional: OFTP2 file description]
 +
*10. file datestamp
 +
*11. file timestamp
 +
*12. file format, formatted as OFTP attribute:
 +
**'<code>F</code>': Fixed format binary file
 +
**'<code>V</code>': Variable format binary file
 +
**'<code>U</code>': Unstructured binary file
 +
**'<code>T</code>': Text
 +
*13. maximum record size ("<code>0</code>" if transfered in binary or text mode)
 +
 
 +
Possible return values are interpreted as shown below:
 +
 
 +
OFTP 1.x session:
 +
*1: Invalid filename.
 +
*2: Invalid destination.
 +
*3: Invalid origin.
 +
*4: Storage record format not supported.
 +
*5: Maximum record length not supported.
 +
*6: File size is too big.
 +
*10: Invalid record count.
 +
*11: Invalid byte count.
 +
*12: Access method failure.
 +
*13: Duplicate file.
 +
*99: Unspecified reason.
 +
 
 +
In addition, in OFTP2 session:
 +
*14: File direction refused.
 +
*15: Cipher suite not supported.
 +
*16: Encrypted file not allowed.
 +
*17: Unencrypted file not allowed.
 +
*18: Compression not allowed.
 +
*19: Signed file not allowed.
 +
*20: Unsigned file not allowed.
 +
 
 +
This feature was first introduced in build 2007-10-16 of Seon.
  
 
== end receive script ==
 
== end receive script ==
Line 42: Line 86:
 
*6. SFID destination  
 
*6. SFID destination  
 
*7. SFID originator  
 
*7. SFID originator  
*8. [optional: OFTPv2 file description]  
+
*8. [optional: OFTP2 file description]
 +
*9. data throughput in kB/sec
 +
*10. file datestamp
 +
*11. file timestamp
 +
*12. used cipher suite in OFTP2 session ("<code>0</code>" for OFTP1.x sessions)
 +
*13. signed EERP request in OFTP2 session ("<code>0</code>" for OFTP1.x sessions)
 +
*14. file format, formatted as OFTP attribute:
 +
**'<code>F</code>': Fixed format binary file
 +
**'<code>V</code>': Variable format binary file
 +
**'<code>U</code>': Unstructured binary file
 +
**'<code>T</code>': Text
 +
*15. maximum record size ("<code>0</code>" if transfered in binary or text mode)
  
 
== start send script ==
 
== start send script ==
Line 52: Line 107:
 
*3. real filename with absolute path  
 
*3. real filename with absolute path  
 
*4. send queue entry comment  
 
*4. send queue entry comment  
*5. partner index  
+
*5. partner index
 +
*6. referenced job ID
 +
*7. referenced file ID
  
 
== end send script ==
 
== end send script ==
Line 63: Line 120:
 
*4. send queue entry comment  
 
*4. send queue entry comment  
 
*5. error indicator: 0 means no error, any other displays an error  
 
*5. error indicator: 0 means no error, any other displays an error  
*6. partner index  
+
*6. partner index
 +
*7. data throughput in kB/sec
 +
*8. referenced job ID
 +
*9. referenced file ID
 +
*10. file datestamp
 +
*11. file timestamp
 +
 
 +
== xERP script ==
 +
Will be started whenever an  EERP is receiver from a  partner. Useful for later-on system-internal cleanup processes.
 +
Parameters:
 +
*1. partner shortname
 +
*2. virtual filename
 +
*3. real filename
 +
*4. comment
 +
*5. error flag: 0=no error, otherwise NERP error code
 +
*6. partner index
 +
*7. file datestamp
 +
*8. file timestamp
 +
*9. originator
 +
*10. destination
 +
*11. referenced job ID
 +
*12. referenced file ID
  
 
== blocked script ==
 
== blocked script ==
Line 73: Line 151:
 
*3. real filename with absolute path  
 
*3. real filename with absolute path  
 
*4. send queue entry comment  
 
*4. send queue entry comment  
*5. partner index  
+
*5. partner index
 +
*6. referenced job ID
 +
*7. referenced file ID
  
 
== debug daemon log script ==
 
== debug daemon log script ==
Line 80: Line 160:
 
Parameters:
 
Parameters:
 
*1: absolute path to the logfile
 
*1: absolute path to the logfile
 +
 +
== license high water mark script ==
 +
Each time the license is checked and a configurable high water mark has been exceeded, this script will be started. This script could be used i.e. for sending an administrator an email with license information or for changing the status of the OFTP system in an system management tool.
 +
 +
Parameters:
 +
*1: configured high water mark in percent
 +
*2: actual amount of configured partners
 +
*3: licensed amount of configured partners
 +
 +
== automatic certificate import script ==
 +
If an automatic certificate exchange import succeeds, this script will be called.
 +
 +
Parameters:
 +
*1. partner shortname
 +
*2. partner index value
 +
 +
== Seon automatic software update event ==
 +
If enabled in the configuration via [[Seon_Core_configuration#Enable_automatic_update_mechanism_.26_Seon_automatic_software_update_script|Enable automatic update mechanism & Seon automatic software update event]], this script or program is executed each time a file with the virtual filename "<code>SEON-UPDATE</code>" is successfully received.
 +
 +
Parameters:
 +
*<code>-f <absolute filename of received file></code>
 +
 +
== Seon automatic update post event ==
 +
If enabled in the configuration via [[Seon_Core_configuration#Enable_automatic_update_mechanism_.26_Seon_automatic_software_update_script|Enable automatic update mechanism & Seon automatic software update event]], this script or program is executed each time after the execution of the update process. The parameters of this post event are:
 +
*1. absolute filename of the update file, passed as first parameter to the Seon update program [[Seon_Core_binaries#seonupdate|seonupdate]]
 +
*2. numeric return code of the update process (0=no error)
 +
 +
== enqueue post script ==
 +
If enabled in the configuration via [[Seon_Core_configuration#enqueue_post-script|enqueue post-script]], this script or program is executed each time a file is enqueued to the send queue. Due to the fact that handled files for OFTP2 transfers (signed, compressed and/or encrypted) get a new temporary file name, this event script will return this new name also.
 +
 +
Parameters:
 +
#partner index value
 +
#absolute filename (new temporary if OFTP2 handled file)
 +
#virtual filename
 +
#comment
 +
#alternative SSID for originator
 +
#alternative SSID for destination
 +
#alternative SFID for originator
 +
#alternative SFID for destination
 +
#priority
 +
#size of file
 +
#original size of file
 +
#alternative OFTP password for originator
 +
#alternative OFTP password for destination
 +
#OFTP release level (see [[Seon_Core_configuration#partner.27s_OFTP_version_column|Configuration: partner's OFTP version column]] for a list of release levels)
 +
#OFTP2 SFIDSEC field
 +
#OFTP2 cipher suite
 +
#OFTP2 compression
 +
#Seon server ID
 +
#send queue index
 +
 +
== Seon API proxy system log event script ==
 +
If enabled in the configuration via [[Seon_Core_configuration#Seon_API_proxy_system_log_event_script|Seon API proxy system log event script]], this script or program is executed each time a critical situation is being logged via Seonapi by the Seon SmartProxy. The user context of this script is the webserver of the Seonapi.
 +
 +
Parameter:
 +
#message
 +
 +
== Event failure script ==
 +
In any case a running event returns a returncode not equal zero ("<code>0</code>"), another script can be called to inform other externals about the situation. The "event failure" event script gets the following parameters:
 +
#script type (see below)
 +
#returncode given by the running event
 +
#the command of the event (absolute path, as configured in the "Events" configuration)
 +
#... all parameters
 +
Since all parameters are being appended to the end of this script (starting as parameter 4), their amount is dynamic and depends on the script type. The following script type number (parameter $1) represent the corresponding event:
 +
#Seon_SCRIPT_START_SESSION: start session
 +
#Seon_SCRIPT_END_SESSION: end session
 +
#Seon_SCRIPT_START_RECEIVE: start receive
 +
#Seon_SCRIPT_END_RECEIVE: end receive
 +
#Seon_SCRIPT_START_SEND: start send
 +
#Seon_SCRIPT_END_SEND: end send
 +
#Seon_SCRIPT_BLOCKED: blocked
 +
#Seon_SCRIPT_XERP: xERP
 +
#Seon_SCRIPT_DEBUGLOG: debug log dump
 +
#Seon_SCRIPT_LIC: license high watermark
 +
#Seon_SCRIPT_UPDATE: update
 +
#Seon_SCRIPT_AUTO_CERT_IMPORT: automatic certificate import
 +
#Seon_SCRIPT_ENQUEUE_POST: enqueue post
 +
#Seon_SCRIPT_ENTERPRISE_JOB_ABORTED: Seon Enterprise aborted job
 +
 +
== Seon Enterprise job abort script ==
 +
If [[Seon_Core_configuration#is_Seon_Enterprise_installed.3F|Seon Enterprise is enabled]] in the configuration ('<code>Configuration</code>' -> '<code>Seon Enterprise</code>' -> '<code>Is Seon Enterprise installed</code>'), this input field is active for configuration, otherwise it will not be displayed. This event will be executed '''synchronously''' every time an Seon job gets into a final aborted state (send jobs: 4; receive jobs: 9). It has the following parameters:
 +
 +
#numeric job ID
 +
#status ID (see above in order to distinguish incoming and outgoing job by its status value)
 +
#absolute path to the job's actual XML file, containing all information i.e. sender, recipient, files, command etc.
 +
 +
Since the script will be executed '''synchronously''', there is no need to clean up the temporary XML file: Seon cleans it up automatically.
 +
 +
 +
== Send queue cleanup event ==
 +
If the send queue daemon is configured to delete successfully sent send queue entries with a configured age, this event can be triggered in order to handle the information that the entry is removed. This event is being executed synchronously and not in parallel, so keep in mind to make this event performant.
 +
 +
Parameters:
 +
*1. partner shortname
 +
*2. virtual filename
 +
*3. real filename with absolute path
 +
*4. send queue entry comment
 +
*5. partner index
 +
*6. referenced job ID
 +
*7. referenced file ID
 +
*8. freely configurable partner event parameter

Latest revision as of 10:53, 7 July 2017

The scripting interface gives you the possibility to start processes during an OFTP connection like managing an EDM system, sending confirmation eMails, deleting files, etc. The scripts have all information available as parameters at this point of time the script will be started.

The scripts are defined via web interface. This configuration is stored in the database, which will be read by every binary on startup and on every configuration reload. If a script is unavailable or not runnable (i.e. execute permissions are missing, user has no read permissions etc.), the script will not be started.

All scripts, except of the start receive script, run in the background and don't influence active Seon transfers during their execution.

The following virtual filenames are reserved and therefor no "normal" script will be run on these files (send, receive, xERP & block):

  • ODETTE_CERTIFICATE_REQUEST: OFTP2 automatic certificate exchange request
  • ODETTE_CERTIFICATE_DELIVER: OFTP2 automatic certificate exchange delivery
  • ODETTE_CRL_REQUEST: OFTP2 automatic certificate revocation list request
  • ODETTE_CRL_DELIVER: OFTP2 automatic certificate revocation list delivery
  • SEON-UPDATE: Seon update package

start session script

Will be started at the beginning of an OFTP session after handshaking SSIDs and passwords.

Parameters:

  • 1. partner shortname
  • 2. partner index value

end session script

Will be started at the end of an OFTP session after receiving an ESID („end session ID“).

Parameters:

  • 1. partner shortname
  • 2. partner index value

start receive script

Will be started at the beginning of an OFTP file transfer from partner to local site after handshaking SFIDs. This script is the only event script which will be started INSIDE the OFTP protocol state machine in order to let a file be received or not! For this feature, the returncode of the event script is used to decline the receipt of a file and to create an SFNA error message (if returncode of script is not equal to zero) or to accept the file, producing an SFPA message.

Parameters:

  • 1. partner shortname
  • 2. virtual filename
  • 3. absolute filename of received file AFTER successful transfer
  • 4. absolute filename of receiving file DURING transfer (temporary)
  • 5. filesize in kilobytes (kB) given by partner (may not be true size)
  • 6. partner index value
  • 7. SFID destination
  • 8. SFID originator
  • 9. [optional: OFTP2 file description]
  • 10. file datestamp
  • 11. file timestamp
  • 12. file format, formatted as OFTP attribute:
    • 'F': Fixed format binary file
    • 'V': Variable format binary file
    • 'U': Unstructured binary file
    • 'T': Text
  • 13. maximum record size ("0" if transfered in binary or text mode)

Possible return values are interpreted as shown below:

OFTP 1.x session:

  • 1: Invalid filename.
  • 2: Invalid destination.
  • 3: Invalid origin.
  • 4: Storage record format not supported.
  • 5: Maximum record length not supported.
  • 6: File size is too big.
  • 10: Invalid record count.
  • 11: Invalid byte count.
  • 12: Access method failure.
  • 13: Duplicate file.
  • 99: Unspecified reason.

In addition, in OFTP2 session:

  • 14: File direction refused.
  • 15: Cipher suite not supported.
  • 16: Encrypted file not allowed.
  • 17: Unencrypted file not allowed.
  • 18: Compression not allowed.
  • 19: Signed file not allowed.
  • 20: Unsigned file not allowed.

This feature was first introduced in build 2007-10-16 of Seon.

end receive script

Will be started after an OFTP file transfer from partner to local site after handshaking EFIDs („end file ID“)

Parameters:

  • 1. partner shortname
  • 2. virtual filename
  • 3. absolute filename of received file AFTER successful transfer
  • 4. error indicator: 0 means no error, any other displays an error
  • 5. partner index
  • 6. SFID destination
  • 7. SFID originator
  • 8. [optional: OFTP2 file description]
  • 9. data throughput in kB/sec
  • 10. file datestamp
  • 11. file timestamp
  • 12. used cipher suite in OFTP2 session ("0" for OFTP1.x sessions)
  • 13. signed EERP request in OFTP2 session ("0" for OFTP1.x sessions)
  • 14. file format, formatted as OFTP attribute:
    • 'F': Fixed format binary file
    • 'V': Variable format binary file
    • 'U': Unstructured binary file
    • 'T': Text
  • 15. maximum record size ("0" if transfered in binary or text mode)

start send script

Will be started at the beginning of an OFTP file transfer from local site to partner after handshaking SFIDs.

Parameters:

  • 1. partner shortname
  • 2. virtual filename
  • 3. real filename with absolute path
  • 4. send queue entry comment
  • 5. partner index
  • 6. referenced job ID
  • 7. referenced file ID

end send script

Will be started at the end of an OFTP file transfer from local site to partner after handshaking SFIDs.

Parameters:

  • 1. partner shortname
  • 2. virtual filename
  • 3. real filename with absolute path
  • 4. send queue entry comment
  • 5. error indicator: 0 means no error, any other displays an error
  • 6. partner index
  • 7. data throughput in kB/sec
  • 8. referenced job ID
  • 9. referenced file ID
  • 10. file datestamp
  • 11. file timestamp

xERP script

Will be started whenever an EERP is receiver from a partner. Useful for later-on system-internal cleanup processes. Parameters:

  • 1. partner shortname
  • 2. virtual filename
  • 3. real filename
  • 4. comment
  • 5. error flag: 0=no error, otherwise NERP error code
  • 6. partner index
  • 7. file datestamp
  • 8. file timestamp
  • 9. originator
  • 10. destination
  • 11. referenced job ID
  • 12. referenced file ID

blocked script

Will be started if a send queue entry will be blocked. If more than one entry will be blocked (i.e. if a connection problem occurs), the script will be executed for every send queue entry seperately.

Parameters:

  • 1. partner shortname
  • 2. virtual filename
  • 3. real filename with absolute path
  • 4. send queue entry comment
  • 5. partner index
  • 6. referenced job ID
  • 7. referenced file ID

debug daemon log script

Every time a debug log will be dumped, this script will be started.

Parameters:

  • 1: absolute path to the logfile

license high water mark script

Each time the license is checked and a configurable high water mark has been exceeded, this script will be started. This script could be used i.e. for sending an administrator an email with license information or for changing the status of the OFTP system in an system management tool.

Parameters:

  • 1: configured high water mark in percent
  • 2: actual amount of configured partners
  • 3: licensed amount of configured partners

automatic certificate import script

If an automatic certificate exchange import succeeds, this script will be called.

Parameters:

  • 1. partner shortname
  • 2. partner index value

Seon automatic software update event

If enabled in the configuration via Enable automatic update mechanism & Seon automatic software update event, this script or program is executed each time a file with the virtual filename "SEON-UPDATE" is successfully received.

Parameters:

  • -f <absolute filename of received file>

Seon automatic update post event

If enabled in the configuration via Enable automatic update mechanism & Seon automatic software update event, this script or program is executed each time after the execution of the update process. The parameters of this post event are:

  • 1. absolute filename of the update file, passed as first parameter to the Seon update program seonupdate
  • 2. numeric return code of the update process (0=no error)

enqueue post script

If enabled in the configuration via enqueue post-script, this script or program is executed each time a file is enqueued to the send queue. Due to the fact that handled files for OFTP2 transfers (signed, compressed and/or encrypted) get a new temporary file name, this event script will return this new name also.

Parameters:

  1. partner index value
  2. absolute filename (new temporary if OFTP2 handled file)
  3. virtual filename
  4. comment
  5. alternative SSID for originator
  6. alternative SSID for destination
  7. alternative SFID for originator
  8. alternative SFID for destination
  9. priority
  10. size of file
  11. original size of file
  12. alternative OFTP password for originator
  13. alternative OFTP password for destination
  14. OFTP release level (see Configuration: partner's OFTP version column for a list of release levels)
  15. OFTP2 SFIDSEC field
  16. OFTP2 cipher suite
  17. OFTP2 compression
  18. Seon server ID
  19. send queue index

Seon API proxy system log event script

If enabled in the configuration via Seon API proxy system log event script, this script or program is executed each time a critical situation is being logged via Seonapi by the Seon SmartProxy. The user context of this script is the webserver of the Seonapi.

Parameter:

  1. message

Event failure script

In any case a running event returns a returncode not equal zero ("0"), another script can be called to inform other externals about the situation. The "event failure" event script gets the following parameters:

  1. script type (see below)
  2. returncode given by the running event
  3. the command of the event (absolute path, as configured in the "Events" configuration)
  4. ... all parameters

Since all parameters are being appended to the end of this script (starting as parameter 4), their amount is dynamic and depends on the script type. The following script type number (parameter $1) represent the corresponding event:

  1. Seon_SCRIPT_START_SESSION: start session
  2. Seon_SCRIPT_END_SESSION: end session
  3. Seon_SCRIPT_START_RECEIVE: start receive
  4. Seon_SCRIPT_END_RECEIVE: end receive
  5. Seon_SCRIPT_START_SEND: start send
  6. Seon_SCRIPT_END_SEND: end send
  7. Seon_SCRIPT_BLOCKED: blocked
  8. Seon_SCRIPT_XERP: xERP
  9. Seon_SCRIPT_DEBUGLOG: debug log dump
  10. Seon_SCRIPT_LIC: license high watermark
  11. Seon_SCRIPT_UPDATE: update
  12. Seon_SCRIPT_AUTO_CERT_IMPORT: automatic certificate import
  13. Seon_SCRIPT_ENQUEUE_POST: enqueue post
  14. Seon_SCRIPT_ENTERPRISE_JOB_ABORTED: Seon Enterprise aborted job

Seon Enterprise job abort script

If Seon Enterprise is enabled in the configuration ('Configuration' -> 'Seon Enterprise' -> 'Is Seon Enterprise installed'), this input field is active for configuration, otherwise it will not be displayed. This event will be executed synchronously every time an Seon job gets into a final aborted state (send jobs: 4; receive jobs: 9). It has the following parameters:

  1. numeric job ID
  2. status ID (see above in order to distinguish incoming and outgoing job by its status value)
  3. absolute path to the job's actual XML file, containing all information i.e. sender, recipient, files, command etc.

Since the script will be executed synchronously, there is no need to clean up the temporary XML file: Seon cleans it up automatically.


Send queue cleanup event

If the send queue daemon is configured to delete successfully sent send queue entries with a configured age, this event can be triggered in order to handle the information that the entry is removed. This event is being executed synchronously and not in parallel, so keep in mind to make this event performant.

Parameters:

  • 1. partner shortname
  • 2. virtual filename
  • 3. real filename with absolute path
  • 4. send queue entry comment
  • 5. partner index
  • 6. referenced job ID
  • 7. referenced file ID
  • 8. freely configurable partner event parameter