X⁵/RX400 Ticket API Documentation
Index
2.3 Deleting a Ticket
2.4 De-/Assigning a Ticket
2.5 Status Calls
3.2.5 A FTPS source example - coming soon...
3.4.1 Defining the media content
3.5.1 Using an existing raw file
3.5.2.1 Text Block
3.5.2.2 Picture Block
3.5.2.3 Barcode Block
1 Introduction
1.1 General function
X⁵/RX400 is the first copy system that knows:
- which data is stored
- at which location
- on which media
- at what time
X⁵/RX400 is the only storage media production system which is able to simultaneously copy individual data onto SSD, USB, CF, MicroSD etc. Just in time copy technology reliably ensures the availability of the right storage media at the right time and the right place.
The X⁵/RX400 Copy System is a development of X-Net Technologies GmbH. It is controlled by the OpenRC - DriveCopy software system, also fully developed by X-Net Technologies GmbH. Typically OpenRC X⁵/RX400 Drivecopy jobs are defined by so called tickets which are in fact JSON files. Therefor X-Net has implemented a special JSON scheme which gets parsed and executed by the OpenRC X⁵/RX400 Drivecopy. It is provided by X-Net Technologies GmbH / Austria and can be changed under the X-Net Closed Source License (X-Net XSL). The source code is available for customers purchasing the X⁵/RX400 Copy System.
This enables our customers to define dynamic and in-time media productions for a smooth integration into their production progress. In the following chapters the structure of a JSON file is described in detail and illustrated with examples.
Note: This is a general description of OpenRC X⁵/RX400 Drivecopy ticket API (Application Programming Interface). Tickets are a highly customer specific thing and there can be a lot of changes and enhancements that can be found in additional documents. Please consult these documentation for more information on your adaption of the OpenRC framework.
This can also result in tickets that don't work as expected from this specification. Please refer to the additional documentation, ask your project leader or consult X-Net support!
1.2 About endpoint
To get Information about a RX400 System you can do a call to its about API endpoint. It will provide you with information about Disk usage, serialnumber, serviceid, licence status and device versions.
GET http://<server>:80/api/about/
{"about":
{"status": true,
"license_active": true,
"serial": "RX400-01001",
"disc_usage":
{
"system":
{
"percent_full": 44.24, "total_size": "19.52 GB", "data_size": "8.64 GB"},
"ssd": {"percent_full": 3.37, "total_size": "457.45 GB", "data_size": "15.43 GB"}
},
"status_display": "Online",
"license_display": "Valid"
},
"device_version": "1.2",
"versions": {"Webinterface": "3.12.0D44", "Service": "3.8.0D13", "Worm": "1.1.0", "Updater": "1.1.0", "Devicemanager": "1.2.0D8"},
"device_variant": "RAS38M Rimage RX400 MedX",
"service_id": "tqfy2"
}
FAQ
What decisions need to be made promptly during implementation?
The most important decisions are defining datasources and ticketing system. Ask yourself where the RX400 system should take its data from. Do you want to push your data onto the RX400 shared storage space and handle storage management on there or do you want the RX400 to pull data from one or more datasources you can define in the ticket? Can you make sure that these datasources are reachable from the RX400 via network? From which system should your Tickets come from? Can that system ensure all data is available in the network before the ticket is send to the RX400?
Which port will have to be used and must be allowed in the firewall?
Port 80 must be available.
What is the difference between a Job and a Ticket?
A Ticket is a description of the process that the RX400 needs to execute in order to fulfill the production of a data medium. It consists of a special JSON scheme which contains information about the data sources, data targets, checksum checks, amount of written media, type of media, event handler, label information and more. This information is parsed and executed by the OpenRC X⁵/RX400 Drivecopy system.
A Job is an instance of execution of a provided Ticket. It contains a tickets, adds a status to it, makes it repeatable and more.
What is the minimal setup for a RX400 system?
The RX400 has demo tickets included. For those please refer the settings. If you want to send external tickets continue reading.
A minimal setup for the RX400 consist of a RX400 Kit, a RX400 comparable USB Stick, a Network and a second Device in this network. If no ticket authorization is set, the second device can send a valid ticket via curl to the RX400. First activate the shared storage space on the RX400, refer to the setting menu for this. Access the RX400 smb share via the RX400 devices IP. Provide data in the share. Write a ticket and define your path as /storage/<your_file_path>/ as "/storage" refers to the local shared storage space. Send the ticket and check if you get a positive response. Wait until your ticket is available on the RX400 device.
How do I use test data?
In the settings you can open the demo ticket options and select a ticket you want to create.
What preparations have to be made before sending a ticket?
All Datasources refered in the ticket must be available for the RX400.
2 Sending a ticket
Tickets can be sent to the X⁵/RX400 Master REST-API via a HTTP POST call. The JSON ticket data has to be sent as the body of the call.
There's also a tool called send.py that sends a local file (from the server) to the X⁵/RX400 Master.
2.1 Sending to the REST-API
To send a ticket to the X⁵/RX400 Master API a HTTP POST request with the json ticket data as its body has to be sent.
Usually the ticket will be sent via the webinterface API endpoint:
http://<server>:80/api/ticket/new/
Alternatively the ticket can be sent directly to the internal Master Service API:
http://<server>:5675/api/ticket/new
The response is a json dictionary. A "status" key describes wether the call was successful.
If it was successsful the assignes ticket id is returned:
{'status': True, 'id': <new ticket id (integer)>}If an error occured while parsing and processing the ticket the error messages are returned in a dictionary containing the errors as a list and grouped by parsing module:
{'status': False, 'errors': {'db': ['missing or invalid data']}}
2.3 Stopping a Ticket
POST http://<server>:80/api/ticket/{id}/stop/
| Request Parameter | ||
| Parameter name | Example | Description |
| id | 1 | Ticket ID |
2.4 Deleting a Ticket
http://<server>:80/api/ticket/{id}/delete/
| Request Parameter | ||
| Parameter name | Example |
Description |
| id | 1 | Ticket ID |
2.5 De-/Assigning a Ticket
Assigning a Ticket
After a job has been started, it must be assigned to a slot in order to be written to the media placed in given slot. Slot and Ticket ID must be provided as query Parameters.
POST http://<server>:80/api/assign/ticket/
| Request Parameter | ||
| Parameter name | Example |
Description |
| ticket_id | 1 | ID of Ticket to be assigned |
| slot_id | 4 | ID of Slot to be assigned |
Slots are numbered from left to right starting with slot_id 1.
If assigning the ticket was successful the started ticket id is returned:
{"status": "true", "redirect": "/status/1"}
If an error occurred while parsing and processing the ticket the error messages are returned in a dictionary containing the errors as a list and grouped by parsing module:
{"status": "false", "errors": {"db": ['missing or invalid data']}}
Deassigning a Ticket
Removing the Assignation of any ticket from a slot.
POST http://<server>:80/api/deassign/ticket/
| Request Parameter | ||
| Parameter name | Example | Description |
| slot_id | 1 | ID of Slot to be assigned |
2.6 Status Calls
What is the difference between a Job and a Ticket?
A Ticket is a description of the process that the RX400 needs to execute in order to fulfill the production of a data medium. It consists of a special JSON scheme which contains information about the data sources, data targets, checksum checks, amount of written media, type of media, event handler, label information and more. This information is parsed and executed by the OpenRC X⁵/RX400 Drivecopy system.
A Job is an instance of execution of a provided Ticket. It contains a tickets, adds a status to it, makes it repeatable and more.
Status of all Tickets
GET http://<server>:80/api/status/ticket/
{
"status": "true",
"data": {[...]}
}
Status of Job with Ticket ID
GET http://<server>:80/api/status/ticket/{id}
| Request Parameter | ||
| Parameter name | Example | Description |
| id | 1 | Ticket ID |
JSON Response:
{"status": "true","data": {...}}
Status of all Jobs
GET http://<server>:80/api/status/job/
{
"status": "true",
"data": {[...]}
}
Status of Job with Job ID
GET http://<server>:80/api/status/job/{id}
| Request Parameter | ||
| Parameter name | Example | Description |
| id | 1 | Job ID |
JSON Response
{"status": "true","data": {...}}
3 Writing a Ticket
3.1 Basics
An OpenRC X⁵/RX400 Drivecopy ticket is a simple JSON file which gets parsed by the jobmaster.
A valid JSON file must contain the mandatory main contents - a "version" number, the "sources" of the data (one or more) and the individual properties of the "job", which are again divided into separate attributes. The minimum requirements for the element "job" are "type", "values", "settings" and "targets".
By now, the current ticket version is "5.0".
{
"version": "5.0",
"sources": [
{
...
},
],
"job": {
...
},
}
| JSON Parameter | ||
| Parameter name | Example | Description |
| version | 5.0 | Ticket System Version (currently 5.0) |
| sources | See 3.2 sources | Defines the storage where the system can source its data from. See 3.2 Sources for more details. |
| job | See 3.3 Jobs | Description of the writing process. See 3.3 Jobs |
3.2 sources
A "sources" element identifies a data source that can be used to obtain data for bumping and/or printing a label on a medium. There are currently five supported sources: The local filesystem ("local"), FTP ("ftp"), SMB ("smb"), NFS ("nfs") and FTPS ("ftps") servers. These different sources are defined in the corresponding "type" element.
Later a source can be referenced in the ticket by its name (subelement "name"). This subelement is a mandatory field and must be specified for all sources to create a ticket. "Name" must be unique and may only be used once per JSON ticket. It is also possible to specify multiple sources of the same or different types.
All types of sources provide the "path" subselement. This element specifies the root directory of a source. The chapter 3.2.1 A local source is an example which specifies the directory "/data" as root directory. When defining the content of each usb device all files must be decalred as a relative path of "/data". Note that operators like ".." and "." are supported.
When the ticket is prepared the files are copied to a temporary cache on the local station.
3.2.1 A local source example
A local source references data which is already stored on the master. For local sources the "path" element is optional, if not provided the default is "/", which means the root folder of the station.
"sources": [
{
"name": "main",
"type": "local",
"path": "/"
},
],
| JSON Parameter | ||
| Parameter name | Example | Description |
| name | main | Name of the source. Used to reference to this source inside the ticket. |
| type | local | Type of source. |
| path | / | Path from system ticket root. Used as relative path when this source is referenced. |
3.2.2 A FTP source example
If a source with type „ftp“ is provided, the system will copy the files from the declared FTP into a temporary folder before the copy process starts. Therefor the system needs the login credential and ip adress. For "ftp" sources the "path" element is default "/", which means the root folder of the station.
Files and directories from a FTP source are searched relative to the FTP home directory of given user.
"sources": [
{
"name": "ftp_local",
"type": "ftp",
"server": "testftp.x-net.at",
"username": "test",
"password": "test",
},
],
| JSON Parameter | ||
| Parameter name | Example | Description |
| name | main | Name of the source. Used to reference to this source inside the ticket. |
| type | ftp | Type of source. |
| server | / | Server Url. System ticket root is given url with the after "/" location. |
| username | test | Username for authentication. If anonymous access is allowed this key is still required. |
| password | test | Password for authentication. If anonymous access is allowed this key is still required. |
3.2.3 A SMB source example
A "smb" source references data that are stored on SMB shares (e.g. Windows shares). In the sources section the "server" and its login data ("username" and "password") is required. For ftp sources the "path" element is default "/", which means the root folder of the station.
The server can either be specified like "//server/share" or "server/share". Files and directories are searched relative to given share and a given "path" declaration.
"sources": [
{
"name": "smb_local",
"type": "smb",
"server": "//server/sharename",
"username": "test",
"password": "test",
},
],
| JSON Parameter | ||
| Parameter name | Example | Description |
| name | main | Name of the source. Used to reference to this source inside the ticket. |
| type | smb | Type of source. |
| server | / | Server Url. System ticket root is given url with the after "/" location. |
| username | test | Username for authentication. If anonymous access is allowed this key is still required. |
| password | test | Password for authentication. If anonymous access is allowed this key is still required. |
3.2.4 A NFS source example
A "nfs" source connects to an NFS server. Authentification is only avaiable by pubic key authorization only and not by login credentials or user authorization.
"sources": [
{
"name": "nfs_local",
"type": "nfs",
"server": "server:/directory",
},
],
| JSON Parameter | ||
| Parameter name | Example | Description |
| name | main | Name of the source. Used to reference to this source inside the ticket. |
| type | nfs | Type of source. |
| server | / | Server Url. System ticket root is given url with the after "/" location. |
3.2.6 Archive as a source
You can use all of the sources above to provide an archive to the X5/RX400. The System will source the data and unpack it locally onto the provided medium. This is recommended if you have a lot of files as copying a archive is a lot quicker than transfering a lot of small files.
For usage please refer to Archive Targets.
3.3 Jobs
The most common jobs are writing jobs which manage to process of writing data onto a medium, verifying the recorded data and printing a label for the medium. A "job" element consists minium of a "type", "values", "settings", "targets" and type-specific elements. The "label" element is optional.
"job": {
"type": "write",
"values": {
...
},
"settings": {
...
},
"targets": [
...
],
"label": {
...
}
}
At this time possible job "type"s is 'write'. write jobs beschreiben (partition erstellen, dateisystem erstellen ,daten erstellen/kopieren) speichermedien und verifizieren die geschrieben daten (beschreibt und verifiziert)
| JSON Parameter | ||
| Parameter name | Example | Description |
| type | write | Kind of job. |
| values | See 3.2 sources | Defines the storage where the system can source its data from. See 3.2 Sources for more details. |
| settings | See 3.3 Jobs | Description of the writing process. See 3.3 Jobs |
| targets | See | Defines what media the data should be written to and allows configuration of the data writing and verification process. |
| label | See | Defines the Label to be printed after finishing the job. |
3.3.1 Values
"Values" can save (customer-specific) meta-information on a job which can be displayed in the user interface. This could for instance be customer-specific identification numbers (id, project-nr, ...).
"values": {
"user": 1,
"ticket_name": "Testprint"
},
| JSON Parameter | ||
| Parameter name | Example | Description |
| user | 1 | The value of "user" can either be the id of the webinterface user as in the JSON example above or arbitrary string/text for example e-mail address. If a ticket is created by the webinterface, the user value contains an id, otherwise if it is created by another system, the value contains an arbitrary text. |
| ticket_name | ticket_1 | required! Displayed in the ticket list of the user interface for an easier identification of tickets. |
| <any> | <any> | Enter any parameters here to be referenced in user interface or in the writing process |
3.3.2 Settings
Settings influence the way a job is processed.
"settings": {
"verify": "md5",
"verify_amount": 1,
"verify_each": 1,
"quantity": 50,
"store": false,
"priority": 10,
"autostart": true,
"autostart_at": '2020-04-01 12:24:33',
},
"targets": [
...
],
"settings": {
"verify": "md5",
"verify_amount": 50,
"verify_each": 50
}
A JSON file can contain two setting elements. One "setting" element refers to "jobs" and the other refers to the "targets" element.
1. job.settings - This settings apply globally and can contain the following elements:
- verify
- verify_amount
- verify_each
- quantity
- store
- priority
- autostart
- autostart_at
| JSON Parameter | ||
| Parameter name | Example | Description |
| verify | md5 |
required! The setting "verify" must be specified. The sums are calculated when the recorded medium is verified. This is also used as a fallback for files that still don't have a checksum up to this point (for whatever reasons). Currently there are three possible values for verify:
|
| verify_amount | 100 | required! It is possible to only verify a certain percentage of the media files. To use this feature the setting "verify_amount" has to be set. The setting accepts values between 0 and 100 (percent), default is 100. If verify is no verify_amount must be 0. |
| verify_each | 1 | This setting specifies if only every x-th medium of a ticket with more that one medium ("quantity") should be verified. A value of 10 on a ticket with quantity 100 leads to verification of every tenth medium. The setting accepts values up to max 100.000, default is 1. |
| quantity | 1 | Amount of jobs to be started when the job is "shot". max 100.000. |
| store | false |
The value "store" specifies if the generated data (e.g. copied files from an FTP server) should be stored or deleted after the ticket is done. The setting accepts either 'true' or 'false', default 'false'. If the value of "store" is set to 'true', the data/folders remain after the copy process is finished. However, if it is set to 'false', the data is copied to a cache directory and deleted after the ticket is complete. |
| priority | 1 | The setting "priority" defines the priority of the ticket. The setting defaults to 1 and valid values are positve and negative integers up to 1000. The higher the priority the faster the ticket is prepared and the corresponding jobs are processed before others. |
| autostart | true | If the setting "autostart" is 'true' the ticket is automatically started ("shot") as soon as it arrives at the jobmaster. If the setting is omitted or 'false' the ticket has to be started via one of the interfaces. |
| autostart_at | The setting "autostart_at" makes it possible to specify a date and time at which the ticket should be started. This setting attribute is dependent on "autostart". Only if "autostart" is 'true', the setting of "autostart_at" becomes active. | |
2. target.settings - A target is always a device and has the corresponding settings for each different device. These settings can include the following elements:
| JSON Parameter | ||
| Parameter name | Example | Description |
| verify | md5 |
The setting "verify" must be specified. The sums are calculated when the recorded medium is verified. This is also used as a fallback for files that still don't have a checksum up to this point (for whatever reasons). Currently there are three possible values for verify:
|
| verify_amount | 100 | It is possible to only verify a certain percentage of the media files. To use this feature the setting "verify_amount" has to be set. The setting accepts values between 1 and 100 (percent), default is 100. |
| verify_each | 1 | This setting specifies if only every x-th medium of a ticket with more that one medium ("quantity") should be verified. A value of 10 on a ticket with quantity 100 leads to verification of every tenth medium. The setting accepts values up to max 100.000, default is 1. |
3.3.3 Targets
A ticket must have a least one or more targets. A target is always a device (e.g. USB or SSD). A ticket has multiple targets if a multiadapter is used (e.g. SSD and two SD adapter). Normally, there is only one target, for example for USB-stick production.
"targets": [
{
"type": "usb",
"data_type": "create",
"devicename": <name of the device>,
"filesystem": "exfat"
"data": [
{
"sourcename": "main",
"mapping": {
"path": "/data/production/<folder_name>/data/",
"destination": "/"
}
}
],
"empty_folders": [
"/folder/hihi/", "folder2/hihi/"
],
"settings": {
"verify": "md5",
"verify_amount": 1
}
}
]
| JSON Parameter | ||
| Parameter name | Example | Description |
| type | usb | Type of device. |
| data_type | create | |
| devicename | usb1 | Any name given to the targets. The targets can be recognized by this name in future use. |
| filesystem | exfat | Filesystem to be put on the target. |
| data | See | Defines the Label to be printed after finishing the job. |
| empty_folders | ["/folder/hihi/", "folder2/hihi/"] | list of paths that should be created with empty folders on the target. |
| settings | See target.settings 3.3.2 | |
3.3.3.1 Archive Targets
For transfer of a lot of small files it is recommended to create an archive before the copy process to the RX400 starts. Copying one Archive is faster than copying a lot of small files.
To use an archive you replace the data parameter from the target example above with a file parameter. In side this file parameter provide
| JSON Parameter | ||
| Parameter name | Example | Description |
| sourcename | main | Name to reference the source. |
| path | /zip-files.zip | Path to be appended to the source. |
If you want to an archive source use the following structure.
"targets": [
{
"type": "usb",
"data_type": "archive",
"devicename": <name of the device>,
"file": {
"sourcename": "main",
"path": "/zip-files.zip",
}
}
],
3.3.4 Label
The "label" section is optional, depending on whether a label print is specified in the settings or not. When set, a label is automatically printed for each device after the copying process. These settings are defined in the block "label" of the JSON file.
| JSON Parameter | ||
| Parameter name | Example | Description |
| type | create |
|
| size | See 3.5 The Label Section | Height and width of Label |
| blocks | See 3.5 The Label Section | List of Label elements |
This section is divided into the following elements - "type", "size" and "blocks". These in turn are divided into sub-elements. See chapter 3.5 The Label Section for a detailed description.
"label": {
"type": "create",
"size": {
"width": 120.0,
"height": 190
},
"blocks": [
{
"type": "picture",
"align": "center",
"position": {
"x": 60,
"y": 15
},
"picture": {
"width": 60,
"height": 30,
"file": {
"sourcename": "main",
"path": "/data/openrc_test/images/1.jpg"
}
}
},
]
}
3.4 Writejob - Writing media
The most common jobs are writing jobs which manage to process of writing data onto a medium, verifying the recorded data and printing a label for the medium.
"job": {
"type": "write",
"values": {
"ticket_name": "Testprint"
},
"settings": {
"store": true,
"verify": "md5"
}
"targets": [
{
"type": "usb",
"data_type": "create",
...
}
]
"label": {
"type": "create",
"size": {
"width": 120,
"height": 190
}
"blocks": [
{
"type": "picture",
...
}
]
}
}
For a detailed description of values, settings, target and label please see the appropriate sections above.
3.4.1 Defining the media content
The information inside the image section control which data is recorded onto the medium. If you want to use an existing RAW image the type 'raw' has to be used in the image section. Otherwise create can be used to define a set of files that should be recorded. The OpenRC X⁵/RX400 Drivecopy determines automatically - according to the image size - which medium should be used.
Using an exisiting RAW image
An existing RAW image can be specified with a fileelement.
"targets": [
{
"type": "usb",
"data_type": "raw",
"settings": {
"verify": "md5",
"verify_amount": 100
},
"file": {
"sourcename": "main",
"path": "/images/image.bin"
}
}
],
Creating a data medium
If you want to record data you'll have to define one or more "data" blocks that consist of a mapping between the source path and the destination path (on the medium). The source path is taken relative to the defined source (see 3.2 Sources).
"targets": [
{
"type": "usb",
"data_type": "create",
"filesystem": "exfat",
"settings": {
"verify": "md5",
"verify_amount": 100
},
"data": [
{
"sourcename": "main",
"mapping": {
"path": "...", //path angeben
"destination": "/"
}
},
{
"sourcename": "main",
"mapping": {
"path": "...",//anderes beispiel wie oben
"destination": "/"
}
}
]
}
],
Data blocks
| JSON Parameter | ||
| Parameter name | Example | Description |
| sourcename | main | Name of source given in the sources given in the sources Section |
| mapping | See example above |
|
3.4.2 Printing a label
After recording (and verifiying) a label can be printed for the medium. It has to be defined in the jobs "label" subsection. Please see the label section for more information!
3.5 The label section
You can either use an existing label (raw) or create a new one (create). It is printed by a label printer (brother or zebra printer) for the device (this process is also called "labeling").
3.5.1 Using an exisiting raw file
An exisiting label has to be a pdf file with the correct size for the printer. The label is referenced relative to a source (see 3.2 Sources) with a "file" element:
"label": {
"type": "raw",
"file": {
"sourcename": "main",
"path": "/images/image1.pdf"
}
}
File Block
In order to reference a file you have to use a file block.
| JSON Parameter | ||
| Parameter name | Example | Description |
| sourcename | main | Name of source given in the sources given in the sources Section |
| path | /images/image1.pdf |
Path of file relative to source path |
3.5.2 Creating a label
A label that should be created dynmaically can include one or more pictures and an individual number of text lines/blocks.
The size dimension of the label is indicated by the "height" and "width" in mm. Each block consists of a "type", an "align" ('left', 'center', 'right'), a "position" sub element and some more elements depending on the block type.
"label": {
"type": "create",
"size": {
"width": 210,
"height": 297
},
"blocks": [
{
"type": "picture",
"align": "center",
"position": {
"x": 60,
"y": 15
},
"picture": {
"width": 60,
"height": 30,
"file": {
"sourcename": "main",
"path": "/images/image1.png"
}
}
},
]
}
Positioning a block
A block can be positioned by the two coordinates x and y and an alignment. The origin is the left down corner of the mediums label.
For example, to place a centered text block in the upper area of a label with the size 60x30 you would define the following coordinates:
"block": [
{
"position": {
"y": 20,
"x": 30
},
"align": "center",
"type": ...,
...
}
],
A x-coordinate of 30 specifies the middle of the label and a centered alignment means that the text block will grow equally on both sides e.g. from -27 to 33 if the text has a width of 6 mm. However if the alignment is "left" it will be displayed from 30 to 36.
For this "block" element the subelement "type" can take three different values:
1. Text block
A text block has to contain a "text" sub element with a text "color", a "font_size", a "font", which should be used for rendering the text, and one or more "lines" sub elements.
| JSON Parameter | ||
| Parameter name | Example | Description |
| color | #000000 |
Colors must be specified in the format rgb(0-225, 0-255, 0-255) or #000000-#FFFFFF with rgb(0,0,0) or #000000 for black and rgb(255,255,255) or #FFFFFF for white. Alternatively all valid css colors can be used, e.g. red, blue, green, white, black. If no color is specified black is used. |
| font | Helvetica |
Speficies Font to be used. Predefined fonts by the pdf standard are "Courier", "Courier-Bold", "Courier-BoldOblique", "Courier-Oblique", "Helvetica", "Helvetica-Bold", "Helvetica-BoldOblique", "Helvetica-Oblique", "Symbol", "Times-Bold", "Times-BoldItalic", "Times-Italic", "Times-Roman", "ZapfDingbats". If you want to use your another font, instead of a font element you add a file block referencing the ttf file. The recommended font for default labels is NotoSans. To Use NotoSans reference a file block with path to /fonts/NotoSans-Regular.ttf Available NotoSans Fonts: NotoSans-Bold.ttf |
| font_size | 16 |
Speficies the font-size |
| lines | ["Test1", "Line2"] |
Lines of text on font. |
"label": {
"type": "create",
"size": {
"width": 210,
"height": 297
},
"blocks": [
{
"type": "text",
"align": "center",
"position": {
"x": 10,
"y": 47
},
"text": {
"color": "#000000",
"font_size": 10,
"lines": [
"X-Net", "Text schwarz"
],
"file": {
"sourcename": "main",
"path": "fonts/NotoSans-Regular.ttf"
}
}
},
{
"type": "text",
"align": "center",
"position": {
"x": 10,
"y": 15
},
"text": {
"color": "#000000",
"font_size": 10,
"font_name": "Times-Roman",
"lines": [
"X-Net", "Text schwarz"
],
}
}
]
}
This example renders a centered text block at y position '47' with one line in black color using specified Times-Roman.
2. Picture block
A picture block contains a "picture" sub element with a file path and its desired size (in mm). The path has to be relative to a previously declared source (see 3.2 Sources). The picture is specified with the width and height. The "proportional" element specifies if the picture should be displayed with the original proportions regardless of the given width/height in the ticket, e.g. if the picture has a size of 100x100 and the ticket states the width and heigth as 50x70 the picture will be displayed as 50x50 if proportional is set to 'true'. If the tag is omitted, false is assumed.
| JSON Parameter | ||
| Parameter name | Example | Description |
| width | 50 | Width of the picture in mm |
| height | 70 |
Height of the picture in mm |
| file | See File Block |
File Block defining Picture source |
| proportional | false |
|
"label": {
"type": "create",
"size": {
"width": 210,
"height": 297
},
"blocks": [
{
"type": "picture",
"align": "center",
"position": {
"x": 105,
"y": 250
},
"picture": {
"width": 60,
"height": 30,
"file": {
"sourcename": "main",
"path": "/data/openrc_test/images/image2.jpg"
},
"proportional": true
}
}
]
}
This example places a picture with size 60x30 mm centered at the top.
3. Barcode block
Despite the name "barcode" the actual barcode is not supported. Only supported scan codes are QR-Code and datamatrix.
The type of the entire Barcode block must be "barcode", only then the barcode block is parsed.
A barcode block contains a "barcode" sub element with properties that specify and scale the barcode.
| JSON Parameter | ||
| Parameter name | Example | Description |
| type | qrcode | Type of barcode "qrcode" or "datamatrix" |
| height | 50 |
height of code in mm |
| width | 50 |
width of code in mm |
| text | Hello World |
Text to be encoded in code |
| rows | 12 |
Maximum number of rows. Default is 12 |
| columns | 12 |
Maximum number of column. Default is 12 |
| options | {"margin": 0, "scale": 1, "data_mode": "alnum"} |
further options -margin: margin around code in mm -scale: no effect keep at 1 -data-mode: "alnum" alphanumeric (characters and numbers), "digits" only digits, "8bits" 8-bit |
"label": {
"type": "create",
"size": {
"width": 50,
"height": 20
},
"blocks": [
{
"type": "barcode",
"align": "left",
"position": {
"x": 35,
"y": 3
},
"barcode": {
"type": "datamatrix",
"width": 10,
"height": 10,
"rows": 12,
"columns": 12,
"text": "www.x-net.at",
"options": {"margin": 0, "scale": 1, "data_mode": "alnum"}
}
},
{
"type": "barcode",
"align": "left",
"position": {
"x": 5,
"y": 3
},
"barcode": {
"type": "qrcode",
"width": 10,
"height": 10,
"rows": 12,
"columns": 12,
"text": "www.x-net.at",
"options": {"margin": 0, "scale": 1, "data_mode": "alnum"}
}
}
]
}
3.6 Events
One or more event handlers can be defined in the ticket, which react to a certain event of a job. As result a json file with the status of the job or ticket is sent to the given destination.
"events": [
{
...
},
{
...
}
],
3.6.1 Event
An event is defined as follows:
| JSON Parameter | ||
| Parameter name | Example | Description |
| type |
See chapter 3.6.2 Event types. |
Defines the name and the type of the event. |
| filename |
See chapter 3.6.3 Filename definition |
Declares the filename of the resulting json file. |
|
destination |
See chapter 3.2 Sources |
Defines the path the generated file will be copied to. |
"events": [
{
"type": "...",
"filename": "...",
"destination": {
"sourcename": "...",
"path": "..."
}
},
]
There are many defined types to react to, that can be grouped into three main groups:
3.6.2 Event Types
An event type represents a certain point in time in the processing of the tickets. There are a few different event types that send feedback from the X5 during production:
Ticket Events
| Eventtype | Definition | |
| ticketStart | The ticket has started. If a ticket has more than one job (quantity greater 1), the signal will be sent at the start (preparing) of the first job. | |
| ticketFinished | The ticket has finished. This means, that all jobs of this ticket have ended. | |
| ticketStop | The ticket has stopped. | |
| ticketStatusChange | Signal at any status change of any job from the ticket (e.g. waiting, preparing, running, error, ...). | |
| ticketPreparingStarted | The preparing process of a ticket has started. | |
| ticketPreparingFinished | The preparing process of a ticket has finished. | |
| ticketPreparingError | During the preparing process an error has occured. | |
| ticketAutodeleteData | The deletion process of the ticket data has started. The data will be deleted automatically after the configured time (See Chapter Settings in X5 Copy System Documentation) has passed after ticket completion. | |
| ticketAutodeleteDB | The deletion process of the database entries has started. The entries will be deleted automatically after the configured time (See Chapter Settings in X5 Copy System Documentation) has passed after ticket completion. | |
The generated json file consists of information on the ticket itself.
Job Events
| Eventtype | Definition | |
| jobStarted | The job has started. | |
| jobFinished | The job has ended. | |
| jobError | An error has occurred in the job. | |
| jobStatusChange | Send a file at any status change of the job (e.g. waiting, preparing, running, error, ...). | |
| jobPrintout | The label was printed (usually after pulling off the usb-stick) | |
The generated json file will only consist of information of the specific job and some general ticket information.
Disc Events
Disc Events are identical to Job Events. These only differ when 2 different types of devices (e.g. USB, SSD) are in use.
- discStarted: The recording of the device was started.
- discFinished: The recording of the device was finished.
- discError: During the recording process an error has occurred.
The generated json file will consist of information of the inserted disc and the corresponding job and some general ticket information.
3.6.3 Filename definition
A filename for the json file can be declared - if not a default filename is created based on the ticket parameters. It is possible to set variables in the filename, e.g. "event_out_test_%(ticket_id)s.json". In summary, these variables can be used for the dynamic generation of the filename:
- ticket_id: The ID of the specific ticket.
- timestamp: The timestamp when the json file was generated.
- date: The date when the json file was generated.
- time: The time when the json file was generated.
- job_id: The ID of the specific job. Can only be used in Job Events.
- disc_id: The ID of the device. Can only be used in Disc Events.
- microsecond: The microsecond when the json file was generated.
The default filename is "event_%(event_type)s_%(timestamp)s_%(ticket_id)s". If the type is a job event, the filename contains the job id ("_%(job_id)s") and if it is a disc event the disc id ("_%(disc_id)s") is appended to the filename. A sample filename: event_jobStarted_20210907_114449_83_241.json
It is recommended to add the "%(microsecond)s" parameter to the filename if you expect events to be generated within a short period of time. Because if a event is generated within the same second as a previous event of the same type and object the already existing even file will be overwritten.
3.6.4 Json File Structure
Depending on the event type, the generated json files has a different structure. The minimal version is the following:
Ticket Event
{
"event_type": "ticketFinished",
"timestamp": "2021-09-06 14:48:52",
"ticket": {
"id": 82,
"status": 300,
"status_msg": "",
"name": "Event Test 3fach",
"quantity": 2,
"finished": 2,
"created_at": "2021-09-06 14:48:14",
"started_at": "2021-09-06 14:48:22",
"size": 146942
},
"job": null,
"disc": null
}
- event_type: Defines at which event type the file has been generated.
- timestamp: Defines the point of time when the event occured.
- ticket: Contains parameters that have been set before to process the ticket.
Job Event
If the type is a job event, the file has an additional block for the set parameters of the processed job and looks as follows:
{
"event_type": "jobStarted",
"timestamp": "2021-09-07 11:44:49",
"ticket": {
"id": 83,
"status": 300,
"status_msg": "",
"name": "Event Test",
"quantity": 2,
"finished": 0,
"created_at": "2021-09-07 11:44:21",
"started_at": "2021-09-07 11:44:40",
"size": 146942
},
"job": {
"id": 241,
"status": 100,
"status_msg": "",
"started_at": "2021-09-07 11:44:49",
"progress": 0.0,
"disc_set": {
"id": 373,
"status": 50,
"removed": false,
"slot": {
"slave_id": 1,
"position": 7
},
"discs": [
{
"id": 373,
"type": "usb",
"serial": "AA00000000000489",
"product_name": "Samsung Flash Drive"
}
]
}
},
"disc": null
}
Disc Event
If the type belongs to the Disc Events, the Json file has a additional block with disc information:
{
"event_type": "discFinished",
"timestamp": "2021-09-06 14:48:52",
"ticket": {
"id": 82,
"status": 300,
"status_msg": "",
"name": "Event Test",
"quantity": 2,
"finished": 0,
"created_at": "2021-09-06 14:48:14",
"started_at": "2021-09-06 14:48:22",
"size": 146942
},
"job": {
"id": 240,
"status": 300,
"status_msg": "verifying files on device usb",
"started_at": "2021-09-06 14:48:43",
"progress": 95,
"disc_set": {
"id": 372,
"status": 100,
"removed": false,
"slot": {
"slave_id": 1,
"position": 5
},
"discs": [
{
"id": 372,
"type": "usb",
"serial": "AA00000000000489",
"product_name": "Samsung Flash Drive"
}
]
}
},
"disc": {
"id": 372,
"type": "usb",
"serial": "AA00000000000489",
"product_name": "Samsung Flash Drive"
}
}
3.7 Plugins
3.7.1 Rimage Hotfolder Plugin
The plugin automatically detects nwp files in the configured folder and converts them into X⁵/RX400 Drivecopy tickets. The following values of the nwp file are evaluated and converted into ticket settings:
- order_id: ticket name (name of the tickets, see chapter 3.3.1 Values)
- copies: quantity (number to be produced, see 3.3.2 Settings)
- volume: dics_name (volume/media name of the data carrier, see 3.3.3 Targets)
- file: data path - the data is this path will be copied to the disc, it must be in the same directory as the nwp file
- merge: label data - this file is evaluated and the scanned data is available in the label (see below)
X-Net can configure the plugin in a way that it deletes all source data (nwp, txt, source directory) after processing or keeps them after processing. NWP files are evaluated only once and their file name is saved internally. A new NWP file must have a different name to be evaluated again.
Customize label templates
The plugin automatically fills a predefined label template from which the label for the medium is generated. The template is located at /etc/drivecopy/rimagehotfolder_label.json and can be edited by the customer at any time. Changes of this file are immediately effective for new incoming tickets.
The template consists of the "Label" block of a ticket (see item 3.5 The label section). All available options and possibilities in the label block are also available here. Additionally, the values from the job with the "merge" option specified text file are also available. The txt file contains values separated by a comma which are available one by one here. For example, the first element can be inserted by "element#0", the second by "element#1", and so on.
See following example which inserts the first and third value from the txt file.
{
"size": {
"height": 29,
"width": 62
},
"type": "create",
"blocks": [
{
"type": "text",
"align": "left",
"text": {
"color": "#000000",
"font_name": "Times-Roman",
"lines": [
"element#0",
"Date: element#2"
],
"font_size": 10
},
"position": {
"y": 5,
"x": 5
}
}
]
}
Previewing and checking of the label template
To preview and check the template there is a command line tool "/opt/usr/drivecopy/lib/plugins/RimageHotfolderWatchdog/configtest.py" which checks the template for possible errors and also generates a sample PDF (to check alignment, sizes, etc.), which is stored under /tmp/test_label.pdf.
Example
Example NWP file:
order_id=0204_151812_PP_00001
media=DVDR
mediasize=500
filetype=PARENT
imtype=ISO09660L2_RELAX, JOLIET
fixate=NOAPPEND
labtype=EDITOR_FMT
rotate=0
volume=TEST Documentation
label=C:\test\ppub.btw
file=\\nt07\TD\Dokumentation\Projekt\CDs\test\NBE1580825511931
merge=\\nt07\TD\Dokumentation\Projekt\CDs\test\NBE1580825511931.txt
copies=1
Example txt file:
"7000000","9000DEMO","2020-10-05","Test Demo","C363DEMO","K731DEMO","Testdata"
The following drivecopy json ticket is generated with the above examples:
{
"version": "5.0",
"sources": [
{
"path": "/",
"type": "local",
"name": "main"
}
],
"job": {
"type": "write",
"values": {
"ticket_name": "0204_151812_PP_00001",
"hotfolder_name": "NBE1580825511935"
},
"settings": {
"verify": "md5",
"verify_amount": 100,
"autostart": true,
"quantity": 1
},
"targets": [
{
"devicename": "TEST Documentation",
"type": "usb",
"data": [
{
"sourcename": "main",
"mapping": {
"path": "/mnt/samba/NBE1580825511931/",
"destination": "/"
}
}
],
"data_type": "create",
"filesystem": "exfat"
}
],
"label": {
"type": "create",
"size": {
"width": 62,
"height": 29
},
"blocks": [
{
"align": "left",
"type": "text",
"text": {
"color": "#000000",
"font_size": 10,
"lines": [
"7000000",
"Date: 2020-10-05"
],
"font_name": "Times-Roman"
},
"position": {
"y": 5,
"x": 5
}
}
]
}
}
}
4 Examples
4.1 Creating a ticket with label printing
{
"version": "5.0",
"sources": [
{
"name": "main",
"type": "local"
}
],
"events": [
{
"type": "ticketFinished",
"filename": "event_out_test_%(ticket_id)s.json",
"destination": {
"sourcename": "main",
"path": "/data/storage/"
}
},
{
"type": "jobStarted",
"destination": {
"sourcename": "main",
"path": "/data/storage/"
}
},
{
"type": "discFinished",
"destination": {
"sourcename": "main",
"path": "/data/storage/"
}
}
],
"job": {
"type": "write",
"values": {
"ticket_name": "Testprint"
},
"settings": {
"store": true,
"verify": "md5"
},
"targets": [
{
"type": "usb",
"type": "create",
"device_name": "LebenAmSee",
"filesystem": "local"
"data": [
{
"sourcename": "main",
"mapping": {
"path": "/data/production/LebenAmSee/data/",
"destination": "/"
}
}
],
"empty_folders": [
"/folder/hihi/", "folder2/hihi/"
]
}
],
"label": {
"type": "create",
"size": {
"width": 120.0,
"height": 190
},
"blocks": [
{
"type": "picture",
"align": "center",
"position": {
"x": 60,
"y": 15
},
"picture": {
"width": 60,
"height": 30,
"file": {
"sourcename": "main",
"path": "/data/openrc_test/images/1.jpg"
}
}
},
{
"type": "picture",
"align": "center",
"position": {
"x": 60,
"y": 80
},
"picture": {
"width": 60,
"height": 30,
"file": {
"sourcename": "main",
"path": "/data/openrc_test/images/2.jpg"
},
"proportial": true
}
},
{
"type": "text",
"align": "center",
"position": {
"x": 10,
"y": 47
},
"text": {
"color": "#000000",
"font_size": 10,
"lines": [
"X-Net", "Text schwarz"
],
"file": {
"sourcename": "main",
"path": "/data/openrc/fonts/lt_21323.ttf"
}
}
},
{
"type": "text",
"align": "center",
"position": {
"x": 85.0,
"y": 47.0
},
"text": {
"color": "#000000",
"font_size": 15,
"lines": [
"X-Net", "Text schwarz"
],
"file": {
"sourcename": "main",
"path": "/data/openrc/fonts/lt_21323.ttf"
}
}
},
{
"type": "barcode",
"align": "center",
"position": {
"x": 13,
"y": 14
},
"barcode": {
"width": 10,
"height": 10,
"margin": 1.3,
"scale": 1.2,
"text": "hihi",
"rows": 3,
"columns": 4
}
}
]
}
}
}
Inhaltspezifische Aktionen