xta-tool 0.1.0

A command line tool for sending and receiving XÖV Transport Adapter (XTA) messages.

xta-tool

A command line tool for sending and receiving XÖV Transport Adapter (XTA) messages.

Usage

Usage: xta [OPTIONS] COMMAND [ARGS]...

  Send and receive xta messages.

Options:
  -c, --config FILE   xta-tool configuration file.
  -p, --profile TEXT  Profile to override base configuration.
  --help              Show this message and exit.

Commands:
  close    Close a message by its ID to acknowledge that it has been read.
  config   Show active configuration values
  get      Get a message by ID and save it to PATH.
  inspect  Inspect a message by ID, showing its transport report.
  ls       List open messages by id.
  new      Get a new message id from the server.
  send     Send a message with ID from PATH.

Config

The tool looks for an optional config file in ~/.xta/config.toml and uses these values as defaults:

# Base URL for all three XTA service ports
base-url: str = "https://localhost:8443"
# Path to ManagementPort
management-port-path = "/services/XTAService/ManagementPort"
# Path to MsgBoxPort
msg-box-port-path = "/services/XTAService/MsgBoxPort"
# Path to SendXtaPort
send-port-path = "/services/XTAService/SendXtaPort"
# Enable verification of XTA server certificate
verify = true
# Root CA certificate (leave empty to use system defaults)
cafile = "~/.xta/ca.crt"
# Client certificate (leave empty to use none)
certfile = "~/.xta/tls.crt"
# Private key of client certificate
keyfile = "~/.xta/tls.key"
# User-Agent in HTTP header
user-agent = "Apache-CXF/4.0.7"
# Print response HTTP headers and SOAP envelope to stderr
verbose = false
# Limit size of file download when encoding to base64 (default 1 MiB)
max-save-base64-size = 1048576
# Limit size of response envelope (default 10 MiB)
max-response-envelope-size = 10485760
# Max entries when listing open messages
max-list-items = 100

# XTA PartyIdentifier used to identify this client
[self-identifier]
# Type
typ = "xoev"
# Category
category = ""
# Name
name = ""
# Certified identifier (for instance: "praefix:behoerdenschluessel") or Wildcard identifier "*"
value = "*"

Additionally, the tool reads ~/.xta/config-myprofile.toml to override config values, if a profile is set by xta --profile myprofile.

Send Message

Upload a message to the XTA server by:

xta send new xta-message.yaml

where xta-message.yaml contains for instance:

metadata:
  service: "urn:some:ServiceName"
  businessScenario:
    code: "XMELD"
    listUri: "urn:de:dataport:codeliste:business.scenario"
    listVersionId: "1.0"
  messageType:
    code: "SomeMessageTypeCode"
  messageTypePayloadSchema: "urn:some:MessageTypePayloadSchema"
  author:
    value: praefix:author-behoerdenschluessel
  reader:
    value: praefix:reader-behoerdenschluessel

message:
  fileName: main.xml
  content: ./path/to/main.xml
  contentType: application/xml
attachments:
  - fileName: extra.txt
    content: ./path/to/extra.txt
    contentType: plain/txt

Additionally, if a content path points to a directory, a ZIP archive containing all files in the directory is send. Furthermore, if a content file path ends in .jinja, the file is rendered as a jinja2 template with context containing config, metdata, message and attachments before sending.

Get Message

Download a message by its ID by:

xta get urn:some:message:id path/to/message

If path/to/message is an existing directory, downloads attached files into the directory and links to them in a message yaml xta-message.yaml (for instance with content: main.xml).

If the output path is not an existing directory, writes attached files as base64 strings directly, meaning content: base64:..., into the message yaml path/to/message.

Install

Install xta as a command line tool by

uv tool install .

References

• XÖV Transport Adapter (XTA)
• Sources for XTA requests and responses:
  • Examples generated with WSDL files for the conformity test by KoSIT using Apache CXF.
  • Content-Type multipart/related for SOAP attachments with MTOM-XOP.