Difference between revisions of "OS4X plugin os4xplugin filerename"

From OS4X
Jump to navigation Jump to search
(New page: == Purpose == Rename all files of an OS4X job according to a specific rule. == Requirements == * File <code>/etc/os4x.conf</code> or configuration file pointed to in environment variabl...)
 
 
(18 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
[[Category:Plugins]]
 
== Purpose ==
 
== Purpose ==
  
Line 6: Line 7:
  
 
* File <code>/etc/os4x.conf</code> or configuration file pointed to in environment variable <code>$OS4X_CFGFILE</code>. Via the used configuration file, the information are retrieved used by the plugin (such as default configuration etc.).
 
* File <code>/etc/os4x.conf</code> or configuration file pointed to in environment variable <code>$OS4X_CFGFILE</code>. Via the used configuration file, the information are retrieved used by the plugin (such as default configuration etc.).
 +
* Either source file or renamed target file must exist. If none of these exist, the plugin stops execution.
  
 
== Configuration ==
 
== Configuration ==
  
 
The target filename can be set up to contain variables. These variables are exchanged by runtime information of the OS4X job, in which context the plugin is run.
 
The target filename can be set up to contain variables. These variables are exchanged by runtime information of the OS4X job, in which context the plugin is run.
 +
 +
Target name can contain an absolute path information or a file name only. The plugin will react on this situation dynamically:
 +
*absolute path information: the calculated target path will be created dynamically
 +
*file name only (without path information): the file will be renamed in the same path it resided before
 +
If (the configurable) virtual filename renaming is active, the virtual filename will be changed to the basename value of the resulting file.
 +
 +
If (the configurable) absolute filename renaming is disabled, the file in the filesystem won't be changed. This influences the following attributes in the job descrpiption:
 +
*absolute filename
 +
*real filename (which is the basename of the absolute filename by default)
  
 
The usable variables are:
 
The usable variables are:
Line 22: Line 33:
 
*%r: recipient partner shortname
 
*%r: recipient partner shortname
 
*%s: sender partner shortname
 
*%s: sender partner shortname
 +
*%t: recipient location name
 +
*%u: recipient department name
 +
*%v: recipient first name
 +
*%w: recipient family name
 +
*%x: recipient address code
 +
*%g: sender location name
 +
*%h: sender department name
 +
*%i: sender first name
 +
*%J: sender family name
 +
*%k: sender address code
 +
*%e: depending on the job direction, the company shortname of the external communication partner:
 +
**incoming jobs: sender's company shortname (= "<code>%s</code>")
 +
**outgoing jobs or undefined job direction: recipient's company shortname (= "<code>%r</code>")
 +
*%E: file extension (the text after the last dot, "<code>.</code>"), i.e. "<code>txt</code>"
 +
*%G: file extension (the text after the last dot, "<code>.</code>", including the last dot "<code>.</code>"), i.e. "<code>.txt</code>"
 +
*%f: filename (basename only, without path)
 +
*%F: filename without extension (basename only, without path)
 +
 +
Starting with OS4X release 2016-12-22, the following variable is also available:
 +
*%V: virtual filename
  
Seit OS4X 3 sind folgende Variablen zusätzlich nutzbar:
+
Starting with OS4X release 2021-06-15, the following variable is also available:
*%t: Empfänger Standortname
+
*%A: job year (short, two digits)
*%u: Empfänger Abteilungsname
+
*%a: ENGDAT Message Reference [UNH0062] (if available, otherwise empty)
*%v: Empfänger Vorname
 
*%w: Empfänger Nachname
 
*%x: Empfänger Adresscode
 
*%g: Sender Standortname
 
*%h: Sender Abteilungsname
 
*%i: Sender Vorname
 
*%J: Sender Nachname
 
*%k: Sender Adresscode
 
  
Seit OS4X 3 Build 20140227 ist folgende Variable nutzbar:
+
Since OS4X 3 Build 20211130 the following variable is available:
*%e: Abhängig von der Auftrags-Richtung, ist diese Variable der Firmenkurzname des externen Kommunikationspartners:
+
*%%: represents the character "<code>%</code>"
**bei Eingangs-Aufträgen: Sender-Firmenkurzname (analog "<code>%s</code>")
+
 
**bei Ausgangs-Aufträgen (oder nicht definierbarer Auftrags-Richtung): Empfänger-Firmenkurzname(analog "<code>%r</code>")
+
== Examples ==
 +
=== incl. directories ===
 +
All examples are based on an OS4X send job with number 76, addressed to company "c-works", with one file "testfile.txt":
 +
/opt/os4x/tmp/%r/os4x_job_%j/%f
 +
will compute to:
 +
/opt/os4x/tmp/c-works/os4x_job_76/testfile.txt
 +
 
 +
----
 +
/opt/os4x/tmp/%D/%r/%j/%e_%F_%j%G
 +
will compute to:
 +
/opt/os4x/tmp/outgoing/c-works/76/c-works_testfile_76.txt
 +
----
 +
A SWAN-like directory behaviour would be:
 +
/opt/os4x/data/%Y/%m/%d/%j/%f
 +
which will compute to:
 +
/opt/os4x/data/2008/03/18/76/testfile.txt
  
== Beispiele ==
+
=== only filename ===
Alle Beispiele basieren auf einem OS4X-Sendeauftrag mit der Nummer 76 von und an Firma "c-works"
+
The following configurations will rename the file in its current directory. The example is based on one job with filename "testfile.txt":
/opt/os4x/tmp/%r/os4x_job_%j/
 
wird zu:
 
/opt/os4x/tmp/c-works/os4x_job_76
 
  
 +
%f_%j
 +
will compute to:
 +
testfile.txt_76
 
----
 
----
  /opt/os4x/tmp/%D/%r/%j
+
  %F_%j%G
wird zu:
+
will compute to:
  /opt/os4x/tmp/outgoing/c-works/76
+
  testfile_76.txt
 
----
 
----
Ein SWAN-ähnliches Konstrukt wäre z.B.:
+
  %e__%F_%j%G
  /opt/os4x/data/%Y/%m/%d/%j
+
will compute to:
welches aufgelöst wird zu:
+
  c-works__testfile_76.txt
  /opt/os4x/data/2008/03/18/76
 
  
== Rückgabewerte ==
+
== Return values ==
0: alles OK
+
0: everything OK
  
1: Configfile (/etc/os4x.conf bzw. Inhalt der Variable "<code>OS4X_CFGFILE</code>") kann nicht gelesen werden oder die hier konfigurierte Datenbank kann nicht verbunden werden
+
1: Configfile (/etc/os4x.conf or value of environment variable "<code>OS4X_CFGFILE</code>", read in as file) cannot be found or database unavailable.
  
2: Lizenzfehler
+
2: License error
  
3: XML-Parameterfile kann nicht geparsed werden
+
3: XML parameter file cannot be parsed
  
4: Datei(en) konnten nicht bewegt werden
+
4: Files cannot be renamed

Latest revision as of 10:44, 27 January 2023

Purpose

Rename all files of an OS4X job according to a specific rule.

Requirements

  • File /etc/os4x.conf or configuration file pointed to in environment variable $OS4X_CFGFILE. Via the used configuration file, the information are retrieved used by the plugin (such as default configuration etc.).
  • Either source file or renamed target file must exist. If none of these exist, the plugin stops execution.

Configuration

The target filename can be set up to contain variables. These variables are exchanged by runtime information of the OS4X job, in which context the plugin is run.

Target name can contain an absolute path information or a file name only. The plugin will react on this situation dynamically:

  • absolute path information: the calculated target path will be created dynamically
  • file name only (without path information): the file will be renamed in the same path it resided before

If (the configurable) virtual filename renaming is active, the virtual filename will be changed to the basename value of the resulting file.

If (the configurable) absolute filename renaming is disabled, the file in the filesystem won't be changed. This influences the following attributes in the job descrpiption:

  • absolute filename
  • real filename (which is the basename of the absolute filename by default)

The usable variables are:

  • %j: job number
  • %d: day of job creation (two digits)
  • %m: month of job creation (two digits)
  • %Y: year of job creation (four digits)
  • %H: hour of job creation (two digits, 24h format)
  • %M: minute of job creation (two digits)
  • %S: second of job creation (two digits)
  • %D: job direction: "incoming" or "outgoing"
  • %r: recipient partner shortname
  • %s: sender partner shortname
  • %t: recipient location name
  • %u: recipient department name
  • %v: recipient first name
  • %w: recipient family name
  • %x: recipient address code
  • %g: sender location name
  • %h: sender department name
  • %i: sender first name
  • %J: sender family name
  • %k: sender address code
  • %e: depending on the job direction, the company shortname of the external communication partner:
    • incoming jobs: sender's company shortname (= "%s")
    • outgoing jobs or undefined job direction: recipient's company shortname (= "%r")
  • %E: file extension (the text after the last dot, "."), i.e. "txt"
  • %G: file extension (the text after the last dot, ".", including the last dot "."), i.e. ".txt"
  • %f: filename (basename only, without path)
  • %F: filename without extension (basename only, without path)

Starting with OS4X release 2016-12-22, the following variable is also available:

  • %V: virtual filename

Starting with OS4X release 2021-06-15, the following variable is also available:

  • %A: job year (short, two digits)
  • %a: ENGDAT Message Reference [UNH0062] (if available, otherwise empty)

Since OS4X 3 Build 20211130 the following variable is available:

  • %%: represents the character "%"

Examples

incl. directories

All examples are based on an OS4X send job with number 76, addressed to company "c-works", with one file "testfile.txt":

/opt/os4x/tmp/%r/os4x_job_%j/%f

will compute to:

/opt/os4x/tmp/c-works/os4x_job_76/testfile.txt

/opt/os4x/tmp/%D/%r/%j/%e_%F_%j%G

will compute to:

/opt/os4x/tmp/outgoing/c-works/76/c-works_testfile_76.txt

A SWAN-like directory behaviour would be:

/opt/os4x/data/%Y/%m/%d/%j/%f

which will compute to:

/opt/os4x/data/2008/03/18/76/testfile.txt

only filename

The following configurations will rename the file in its current directory. The example is based on one job with filename "testfile.txt":

%f_%j

will compute to:

testfile.txt_76

%F_%j%G

will compute to:

testfile_76.txt

%e__%F_%j%G

will compute to:

c-works__testfile_76.txt

Return values

0: everything OK

1: Configfile (/etc/os4x.conf or value of environment variable "OS4X_CFGFILE", read in as file) cannot be found or database unavailable.

2: License error

3: XML parameter file cannot be parsed

4: Files cannot be renamed