xta-tool 0.3.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: ~/.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 $XDG_CONFIG_HOME/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, or empty to use system defaults (where path is relative to any config directory)
cafile = "ca.crt"
# Client certificate, or empty to use none (where path is relative to any config directory)
certfile = "tls.crt"
# Private key of client certificate, or empty to use none (where path is relative to any config directory)
keyfile = "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, or empty to use none
category = ""
# Name, or empty to use none
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:fim:Wohngeld-Mietzuschuss:1.5"
  businessScenario:
    code: "FIM-WOHNGELD_DATA"
    listUri: "urn:de:xta:codeliste:business.scenario"
    listVersionId: "3.6"
  messageType:
    code: "fim.S05000227.05000227001005"
  messageTypePayloadSchema: "urn:xoev-de:xfall:standard:fim-s05000227_1.5"
  author:
    category: "Wohngeldportal"
    value: "wgp:010500100000"
  reader:
    category: "Wohngeldbehörde"
    value: "wgb:051110000000"

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.
• Example from Wohngeld-FIM 4.1 XTA-Transportauftrag