xta-tool 0.2.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   Use a custom configuration file location.  [default:
                      /var/home/jan/.xta/config.toml]
  -p, --profile TEXT  Use a configuration profile.
  --version           Show the version and exit.
  --help              Show this message and exit.

Commands:
  close    Close a message by its ID, acknowledging 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 loads configuration values from ~/.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 = "*"

Configuration values may be overridden by profile configuration files. For instance, if XTA_TOOL_CONFIG=path/to/config.toml XTA_TOOL_PROFILE=profile1,profile2,profile3 is set, it reads values from path/to/config.toml and then from path/to/config-profile{1,2,3}.toml.

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

If a content path points to a directory, the tool sends all files in the directory as a ZIP archive.

If a content file path ends in .jinja, the tool sends the file after rendering it as a jinja2 template with config, metdata, message and attachments in the templating context.

Get Message

Download a message by its ID from the XTA server by:

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

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

If the output path is not an existing directory, the tool writes attached files directly as base64 strings, 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.