OS4X Core event web API calls

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

The events are configured via web interface. This configuration is stored in the database, which will be read by every binary on startup and on every configuration reload. Web request events must start with "http://" or "https://" in case-sensitive written mode.

All events, except of the start receive event, run in the background and don't influence active OS4X transfers during their execution. The parameters of the web request will be provided as POST parameter.

The following virtual filenames are reserved and therefor no "normal" event API call 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
• OS4X_UPDATE: OS4X update package
• OFTP_COMMUNICATION_SETUP: OFTP2 PDX communication setup file

start session web API call

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

Parameters:

• event: start_session
• shortname: partner shortname
• idx: partner index value
• event_parameter: freely configurable partner event parameter

end session web API call

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

Parameters:

• event: end_session
• shortname: partner shortname
• idx: partner index value
• esidreas: value of ESIDREAS (reason code)
• event_parameter: freely configurable partner event parameter

start receive web API call

Will be started at the beginning of an OFTP file transfer from partner to local site after handshaking SFIDs. This web request API call is the only one which will be started INSIDE the OFTP protocol state machine in order to let a file be received or not! For this feature, the response of the request is used to decline the receipt of a file and to create a SFNA error message (non-empty numeric value of non-zero) or to accept the file, producing a SFPA message.

Parameters:

• event: start_receive
• shortname: partner shortname
• virt_filename: virtual filename
• abs_filename: absolute filename of received file AFTER successful transfer
• tmp_filename: absolute filename of receiving file DURING transfer (temporary)
• filesize_kb: filesize in kilobytes (kB) given by partner (may not be true size)
• idx: partner index value
• dest_sfid: SFID destination
• orig_sfid: SFID originator
• oftp2_filedesc: OFTP2 file description
• file_datestamp: OFTP2 file datestamp
• file_timestamp: OFTP2 file timestamp
• event_parameter: freely configurable partner event parameter
• format: file format, formatted as OFTP attribute:
  • 'F': Fixed format binary file
  • 'V': Variable format binary file
  • 'U': Unstructured binary file
  • 'T': Text
• record_size: maximum record size ("0" if transferred in binary or text mode)

Possible response values are interpreted as shown below. It must be unformatted (non-JSON, non-XML or whatsoever). The HTTP response code must be between 200 and 299.

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.

end receive web API call

Will be started after an OFTP file transfer from partner to local site after handshaking EFIDs („end file ID“). The file will be appended to the web request as entity "file" in the multipart MIME request. The request will be sent as "multiform/data" request.

Parameters:

• event: end_receive
• shortname: partner shortname
• virt_filename: virtual filename
• abs_filename: absolute filename of received file AFTER successful transfer
• error: error indicator: 0 means no error, any other displays an error
• idx: partner index value
• dest_sfid: SFID destination
• orig_sfid: SFID originator
• oftp2_filedesc: OFTP2 file description
• throughput: data throughput in kB/sec
• file_datestamp: OFTP2 file datestamp
• file_timestamp: OFTP2 file timestamp
• oftp2_cipher: used cipher suite in OFTP2 session ("0" for OFTP1.x sessions)
• signed_eerp_req: signed EERP request in OFTP2 session ("0" for OFTP1.x sessions)
• format: file format, formatted as OFTP attribute:
  • 'F': Fixed format binary file
  • 'V': Variable format binary file
  • 'U': Unstructured binary file
  • 'T': Text
• event_parameter: freely configurable partner event parameter
• record_size: maximum record size ("0" if transferred in binary or text mode)

start send web API call

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

Parameters:

• event: start_send
• shortname: partner shortname
• virt_filename: virtual filename
• abs_filename: absolute filename of received file AFTER successful transfer
• comment: send queue entry comment
• comment2: send queue entry comment #2
• idx: partner index
• ref_job: referenced job ID
• ref_file: referenced file ID
• orig_sfid: originator SFID
• dest_sfid: destination SFID
• init_filename: real filename with absolute path before OFTP2 security operation(s)

end send web API call

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

Parameters:

• event: end_send
• shortname: partner shortname
• virt_filename: virtual filename
• abs_filename: absolute filename of received file AFTER successful transfer
• comment: send queue entry comment
• comment2: send queue entry comment #2
• idx: partner index
• ref_job: referenced job ID
• ref_file: referenced file ID
• orig_sfid: originator SFID
• dest_sfid: destination SFID
• init_filename: real filename with absolute path before OFTP2 security operation(s)
• error: error indicator: 0 means no error, any other displays an error
• throughput: data throughput in kB/sec
• file_datestamp: OFTP2 file datestamp
• file_timestamp: OFTP2 file timestamp
• event_parameter: freely configurable partner event parameter
• init_filename: real filename with absolute path before OFTP2 security operation(s)

xERP web API call

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

• event: xerp
• shortname: partner shortname
• virt_filename: virtual filename
• real_filename: real filename
• comment: send queue entry comment
• comment2: send queue entry comment #2
• error: error indicator: 0 means no error, any other displays an error
• idx: partner index
• file_datestamp: OFTP2 file datestamp
• file_timestamp: OFTP2 file timestamp
• orig_sfid: originator SFID
• dest_sfid: destination SFID
• event_parameter: freely configurable partner event parameter
• init_filename: real filename with absolute path before OFTP2 security operation(s)

Beware that the originator of an xERP is the destination of the file!

blocked web API call

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 event will be executed for every send queue entry separately.

Parameters:

• event: blocked
• shortname: partner shortname
• virt_filename: virtual filename
• real_filename: absolute filename of received file AFTER successful transfer
• comment: send queue entry comment
• comment2: send queue entry comment #2
• idx: partner index
• ref_job: referenced job ID
• ref_file: referenced file ID
• file_datestamp: OFTP2 file datestamp
• file_timestamp: OFTP2 file timestamp
• event_parameter: freely configurable partner event parameter
• init_filename: real filename with absolute path before OFTP2 security operation(s)

Send queue entry send try increase web API call

Every time a send queue entry increases the amount of send tries, this event will be executed.

Parameters:

• event: increased
• shortname: partner shortname
• virt_filename: virtual filename
• real_filename: absolute filename of received file AFTER successful transfer
• comment: send queue entry comment
• comment2: send queue entry comment #2
• idx: partner index
• ref_job: referenced job ID
• ref_file: referenced file ID
• event_parameter: freely configurable partner event parameter
• init_filename: real filename with absolute path before OFTP2 security operation(s)
• file_datestamp: OFTP2 file datestamp
• file_timestamp: OFTP2 file timestamp
• actual_sendtry: actual send try
• max_sendtries: maximum amount of send tries configured

debug daemon log web API call

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

Parameters:

• event: increased
• logfile: absolute path to the logfile

license high water mark web API call

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

Parameters:

• event: license_highwater_mark
• amount_of_partners: actual amount of configured partners
• amount_licensed_partners: licensed amount of configured partners

automatic certificate import web API call

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

Parameters:

• event: autocert_import
• shortname: partner shortname
• idx: partner index
• event_parameter: freely configurable partner event parameter

OS4X automatic update post API call

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

• event: update_post
• filename: absolute filename of the update file, passed as first parameter to the OS4X update program os4xupdate
• rc: numeric return code of the update process (0=no error)

enqueue post web API call

If enabled in the configuration via enqueue post-script, this event 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 will return this new name also.

Parameters:

• event: enqueue_post
• idx: partner index value
• real_filename: absolute filename (new temporary if OFTP2 handled file)
• virt_filename: virtual filename
• comment: comment
• orig_alt_ssid: alternative SSID for originator
• orig_alt_sfid: alternative SFID for originator
• orig_alt_pwd: alternative OFTP password for originator
• dest_alt_ssid: alternative SSID for destination
• dest_alt_sfid: alternative SFID for destination
• dest_alt_pwd: alternative OFTP password for destination
• priority: priority
• filesize: size of file
• orig_filesize: original size of file
• oftp_version: OFTP release level (see Configuration: partner's OFTP version column for a list of release levels)
• oftp2_sfidsec: OFTP2 SFIDSEC field
• oftp2_cipher: OFTP2 cipher suite
• oftp2_compression: OFTP2 compression
• server_id: OS4X server ID
• send_queue_index: send queue index
• init_filename: Original filename (same as absolute filename if original file is untouched; changed against absolute filename if original file is touched by OFTP2 mechanisms)
• event_parameter: freely configurable partner event parameter

OS4X Enterprise job abort script

If OS4X Enterprise is enabled in the configuration ('Configuration' -> 'OS4X Enterprise' -> 'Is OS4X Enterprise installed'), this input field is active for configuration, otherwise it will not be displayed. This event will be executed synchronously every time an OS4X 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: OS4X 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
• 9. send queue entry comment #2
• 10. file datestamp
• 11. file timestamp
• 12. real filename with absolute path before OFTP2 security operation(s)