v2.2.0

🚑️ Fixed

• 💥 KeyError when decoding JSON:
  In situations where Citrix reports a state that is not reflected in
  psytricks.mappings, decoding of the JSON response failed with a KeyError
  in psytricks.decoder.parse_powershell_json. This is now fixed by catching 🥅
  any unknown mapping error and replacing it with undefined-mapping-<index>,
  where <index> is the integer value reported by Citrix that should be added
  to the corresponding mapping dict. This approach ensures that the function
  doesn't fail while still indicating clearly what went wrong.

✨ Added

• 🔌📑 More PowerState mappings:
  The dict psytricks.mappings.power_state now contains mappings for index
  numbers 10 (NotSupported) and 11 (VirtualMachineNotFound) that
  apparently got added in CVAD versions newer than 2203 (note that it's not
  required for the Delivery Controller to have a more recent version for this to
  show up, it is actually sufficient if one of the connected machines is running
  a corresponding VDA version, e.g. 2507).
• 🏝️ Lazy connection checking:
  • The constructor of psytricks.wrapper.ResTricksWrapper is now having an
    additional optional parameter lazy. If this is set to True (default is
    False), the initial connection check will not be performed during
    instantiation but is deferred until the connection is actually required.
  • psytricks.wrapper.ResTricksWrapper.send_get_request now takes an
    additional optional parameter auto_conn (default is True) that can be
    used to prevent it from calling self.connect(), which is required to avoid
    a recursive loop triggered by the new lazy connection approach described
    above.
• 🕵🏼 Read-only / passive operation:
  The instance attribute psytricks.wrapper.ResTricksWrapper.read_only has been
  added in order to intercept any request that would perform a state change to
  the CVAD platform and turn it into a WARNING level log message. This is
  meant for testing applications against a production CVAD or for creating
  monitoring-only tools.
• 👷🚚🌍🎪 Build and publish releases via GitHub Actions:
  • Python 🐍 packages 📦 are now built through a GitHub Action workflow.
  • They're automatically published on 🎪 PyPI.
  • Packages 📦 with the Windows service 🏭 are created and attached to the
    assets of their respective GitHub release.
  • New releases will automatically trigger an update to the
    API docs available at imcf.one.

🚀 Improved

• 📝✨ API documentation:
  While the exact structure of the data returned by any of the wrapped calls to
  the CVAD infrastructure depends on the behavior of the 👽️ Citrix toolstack,
  the respective methods now describe the expected keys of the delivered dicts
  for CVAD version 2203 in their docstrings, for example
  psytricks.wrapper.ResTricksWrapper.get_machine_status.
• 📢📅 Logging:
  The ResTricksService startup messages now contain more timestamps, to allow
  for identifying the age of an entry in the log files.

Full Changelog: v2.1.6...v2.2.0

v2.1.6

Fixed

• Set-AccessUsers() in psytricks-lib.ps1 did not work correctly if multiple usernames were specified. This is now fixed by foce-converting the given string into an array, splitting at "," characters. This directly affects the functionality for adding / removing multiple users at once via psytricks.wrapper.ResTricksWrapper.set_access_users() and psytricks.wrapper.PSyTricksWrapper.set_access_users().

Full Changelog: v2.1.5...v2.1.6

v2.1.5

Changed

• Type hints and docstrings were fixed, some of them were indicating the wrong return types.

Full Changelog: v2.1.4...v2.1.5

v2.1.4

Changed

• Logging level changes only, reducing messages higher than debug.

Full Changelog: v2.1.3...v2.1.4

v2.1.3

Changed

• The version check done when instantiating a psytricks.wrapper.ResTricksWrapper
  object now allows for a PATCH level mismatch as by definition the API is
  still expected to be fully compatible. It issues a warning-level log message
  to indicate the mismatch though. This allows for easy fixes on the Python
  side of the package without having to re-install / upgrade the server side
  each time. A small fix to respect pre-releases following the semantic
  versioning rules has been added as well.

v2.1.2

Changed

• Updated loguru dependency to 0.7.0.

v2.1.1

No functional / code changes, only lowering minimal Python version to 3.9.

v2.1.0

PowerShell changes

The JSON returned by the REST server was completely missing the Status object, this is now fixed. Additionally, that object now also contains a Timestamp property to report (in seconds since the epoch, a.k.a. Unix time) when the response has been generated.

Added ✨

• The constructor of psytricks.wrapper.ResTricksWrapper is now doing a connection check to the defined server upon instantiation.
• In addition it was extended by an optional argument verify (defaulting to True) for requesting the server version to be verified against the client version.
• If verify is set to True exceptions will be raised in case the connection check fails or if a version mismatch is detected.

Changed 🏗

• In case the core HTTP request (GET or POST) fails in any of the wrapper methods, the corresponding exception is now re-raised to make this visible to the calling code. Previously only log messages were generated and the exceptions had been silenced explicitly.
• Each HTTP response is now expected to contain a JSON payload. In case the HTTP status code is indicating an issue, the Status attributes of the returned JSON are printed to the log to facilitate debugging.
• The psytricks.wrapper.ResTricksWrapper.perform_poweraction method now returns the details on the power action status of the given machine.

Fixed 🩹

• Citrix status values and PowerShell timestamps are now properly mapped also in psytricks.wrapper.ResTricksWrapper methods. Previously this had been the case in psytricks.wrapper.PSyTricksWrapper methods only.

v2.0.0

Common

A REST server (restricks-server.ps1) written in PowerShell was added to facilitate and speed up interaction with the CVAD / Citrix toolstack. See the installation instructions for details on how to use it and please be aware that this is very much in an infant state 🍼.

NOTE: this is an alternative to the original way of calling PowerShell as a Python subprocess (requiring the Python code to be executed in a user context that has access to the Citrix Broker Snap-In and that has appropriate permissions configured on the Delivery Controller). Wrapping this into a REST service that is reachable via HTTP allows to run the Python code in a completely independent context.

Changed

• 🧨 BREAKING 🧨
  • psytricks.wrapper.PSyTricksWrapper.send_message is now requiring the details (style, title and text) of the message to send directly, unlike before where a file was being read. If the file use-case is required again it can be simply wrapped around the method call. This change is done to keep consistency with the newly introduced REST wrapper class (see below).
  • All action methods (requesting data or state changes from Citrix) in psytricks.wrapper.PSyTricksWrapper have dropped the kwargs parameter. They were initially implemented to simplify the call from within psytricks.cli.run_cli but are basically just adding confusion.
  • To accommodate for the above changes the CLI command sendmessage now has two additional command-line options: --title (mandatory) to set the message title and --style (optional) to set the message icon. The previously existing --message option now expects the body as a string (may contain \n for linebreaks), not the path to a message file any more.

Added

• An additional wrapper class psytricks.wrapper.ResTricksWrapper 🎪 has been added to interface with the newly introduced REST service. Apart from feeling much less awkward than the subprocess way, this also happens to be orders of magnitude faster 🎢🎡.
• Added psytricks.literals to improve type checking and documentation.

v1.0.0

Changed

• 🧨 BREAKING 🧨
  • The PowerShell wrapper script parameter JsonConfig has been dropped in
    favor of the new AdminAddress that gives the address of the Delivery
    Controller to use directly. This is done for two reasons: to be more
    consistent with the original Citrix commands and to get rid of the overhead
    of needing an extra file when it contains only one single setting.
  • To accommodate for this, the PSyTricksWrapper constructor changed its
    only parameter from conffile to deliverycontroller.
  • Along those lines also the CLI tool switched from using the parameter
    --config to --cdc (short for Citrix Delivery Controller).
• When requesting session details (PSyTricksWrapper.get_sessions) the
  following properties will now also be reported:
  • ClientAddress
  • ClientName
  • ClientPlatform
  • ClientProductId
  • ClientVersion
  • ConnectedViaHostName

Added

• Two new arguments for the command line tool:
  • --version
  • --outfile - to write the results into a file