> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/hypersim/readme/release-notes-2024.md).

# Release Notes 2024

## Version: 2024.4.4

### Bug fixes

* **I/O Interface**: Fixed Oregano card initialization in 1PPS and IRIG-B modes.

***

## Version: 2024.4.2

### Improvements

* **OPAL-RT Board**: Added logs that show the PWM output configuration during the load of the model.

### Bug fixes

* **IEC 61850**: Fixed Sampled Values publishing rate variance depending on the simulator’s CPU speed.
* **IEC 61850**: Fixed behaviour of the configuration revision parameter for Sampled Values 9-2LE items, by making it visible in the GUI and by setting its default value to 1.
* **MODBUS Slave**: Fixed reception of multiple registers of 32 bits written by the master with operation code 0x10.

***

## Version: 2024.4

### New features

* A new Control Microgrid library is available, offering multiple control blocks:
  * Active Power Dispatch
  * BESS Management
  * Curtailment Management
  * Islanding Management
  * Load Management
  * Reactive Power Dispatch
* A new option has been added that allows to define a number of steps to be executed without IOs at the beginning of the simulation to improve simulation performance.
  * See the “Number of steps before enabling I/Os” option in the Simulation Settings | Advanced
  * Note that before that, HYPERSIM was always executing 100 steps without IOs. This new option simply allows to change this value.
* It is now possible to get the license number and target number in the license panel of the Target Manager
* **Python API**: A new methodgetVersion is available to get the current HYPERSIM version
* **Python API**: Multiple new simulation and task mapping settings can now be updated using the setPreference and getPreference methods. These settings are now listed in the Simulation Settings and the Task Manager - Summary and Preferences documentation.
* **Dashboard**: Added the Alias feature to easily rename data points.
* **Dashboard**: Added the option to share panel between project.
* **Dashboard**: Expanded Navigation Options: URL and inter-panel navigation now available across Text, Image, and Shape widgets.
* **Dashboard**: Added X-Y visualization for the graph widget.
* **Dashboard**: Added new shapes to Switch Widget.
* **Dashboard**: Added customization options for background and border colors in the Text widget.
* **Dashboard**: Added labels to navigation buttons in the interface.
* **Dashboard**: Added keyboard navigation for the data point picker.
* **PowerFactory Import**: Added support of subsystems documented in PowerFactory - Supported Features and Limitations - Import of subsystems
* **PowerFactory Import**: Added support of the WEHGOV turbine governor blocks
* **PowerFactory Import**: Added support of the GAST turbine governor blocks
* **PSS/E Import**: The following components are now imported as native HYPERSIM components
  * IEESGO
  * GGOV1
  * DEGOV
  * IEEEG1
  * ESAC6A
* **PSS/E Import**: Added warning message when a model is imported without a dyr file
* **CAN**: Added support for the CAN driver using the Kvaser PCIe card
* **IEC 61850**: Added support for sending a report to multiple MMS client instances
* **MODBUS Slave**: Added support for TCP slave IDs up to 255
* **OPAL-RT Board**: Added capability to program multiple OP4810-IO/OP4815-IO platforms in parallel during the load of a model
* **OPAL-RT Board**: Added the display of extra information such as the IP and MAC addresses to the detection of OP4810-IO/OP4815-IO platforms

### Improvements

\*Prevent the creation of an I/O Interface with a duplicated name.

* It is now possible to start/stop the recording of signals directly in the datalogger control center. Note that the control center has to be launched before the simulation has started.
* Error highlight in HYPERSIM console has been improved.
* An error message is now displayed when the network adapter of the localhost target is set to an invalid IP address in the Target Manager. Note that before that, the HYPERSIM engine would simply crash.
* The Target Manager license panel now warns when no license is installed.
* The Load Flow Viewer now has a “clear all” contextual menu to clear the content of the “Output” tab.
* Firmware and Hardware mismatches are now clearly stated in the simout console.
* **Dasboard**: Improved performance of tables for very large models.
* **Dasboard**: Enhanced the graduated widget by allowing inversion of the minimum and maximum values.
* **Dasboard**: Improved the size and layout of the floating library for better usability by downsizing it.
* **Dasboard**: Improved the horizontal layout of the graduation for the slider and thermometer widgets.
* **Dasboard**: Improved the behavior of the color picker when opening and closing.
* **Dasboard**: Improved the performance monitoring tool for panels by incorporating backend data.
* **Dasboard**: Improved model synchronization to prevent loss of connections in Dashboards after closing and reopening the project.
* **Dashboard App Server**: Improved the compatibility matrix by removing the Client Version Min and Max option to a fixed version per client.
* **FPGAScope**: Signal display order in the FPGA Scope now follows the order defined in the FSD file
* **PSS/E Import**: Improved import time performance for large models
* **I/O Interfaces**: Allow signals to be renamed in the I/O Interface Configuration window
* **I/O Interfaces**: Improved stability by ensuring that asynchronous computation components of I/O interfaces run either on core 0 or on a dedicated core, but not on the core of the simulation itself
* **OPAL-RT Board**: Improved workflow by keeping connections even if a raw data point's name changes
* **OPAL-RT Board**: Improved workflow by skipping bitstream programming if OP4810-IO/OP4815-IO platforms are configured with an empty chassis name and/or an empty IP address

### Bug fixes

* Fixed an issue where the RT Monitor table was displaying incorrect status in the “Enabled” column when scrolling the table
* Fixed the Start/stop timeout defined in HYPERSIM (Simulation Settings → Advanced → Simulation Server) that was not always correctly taken into account.
* Fixed an issue during analyse when a UCM with selected sensors was duplicated.
* Fixed an issue where the Activation Tool was not responding when applying a license from Help\&Support.
* Fixed an issue where the HYPERSIM engine was crashing when analyzing the network from the Load Flow Viewer.
* Fixed an issue where the HYPERSIM engine would crash with certain parameter configuration of the 3-winding, w/sat + tap +dec block. The engine would crash when the Vmin parameter was greater than the Vmax parameter, or the Vnom parameter was not between Vmax and Vmin
* Fixed a HYPERSIM engine crash when a file that is not a .pun was used in line components.
* Fixed an issue that was slowing down the load flow computation in some cases.
* Fixed a bug where Load Flow properties weren't being saved when the model was saved.
* Fixed an issue where the Frequency Protection block was not taking into account the initial value.
* Fixed an issue where changes to parameters in the Load Flow window were not applied, despite appearing to update visually.
* Fixed an issue where Line with Line generator did not take the frequency and the ground resistivity into consideration.
* **Dashboard**: Fixed a minor issue where text was not fully displayed in the dropdown widget.
* **Dashboard**: Fixed minor issues on edition in panel of the Text widget.
* **Dashboard**: Fixed an issue where value formatting was not applied immediately after changing preferences.
* **Dashboard**: Fixed unnecessary scrollbars appearing in the shortcuts popout.
* **Dashboard**: Fixed a style flicker issue when resizing the script view.
* **Dashboard**: Fixed an issue where instantiated widgets were not migrated to newer versions.
* **Dashboard**: Fixed the back-and-forth effect issue in the tag group widget.
* **Dashboard**: Fixed the connection table issue where matrix data points appeared as vectors.
* **Dashboard Installer**: Fixed the 'Dashboards seem unavailable' bug that occurred when installing to a non-default path.
* **Dashboard Installer**: Fixed an installation issue when installing on a drive other than “C://” .
* **Dashboard Installer**: Fixed an issue where the tasklist was not available on client computers by adding a fallback to WMIC.
* **Dashboard Installer**: Fixed the issue of permissions not being set for clients with multiple user accounts on the same computer.
* **FPGAScope**: Fixed potential ScopeView crash when making an FPGA Scope acquisition with multiple FPGAs
* **FPGAScope**: Fixed capability to differentiate boards of the same family type
* **FPGAScope**: Fixed crash of simulation when using an RT core
* **PSCAD Import**: Fixed an issue when several master:import shared the same name in a given subsystem
* **PSCAD Import**: Fixed missing items in the PSCAD input model intermediate library
* **OPAL-RT Board**: Fixed reload of bitstreams on SGI systems
* **OPAL-RT Board**: Fixed bitstream configuration update mechanism to:
  * keep the name of raw data signals
  * keep the byte and bit offsets of raw data signals
  * keep the state of the ‘Enable FPGA scope’ check-box
  * support merging configurations for OP48H20 cards
* **OPAL-RT Board**: Fixed filter for bitstream file browser
* **OPAL-RT Board**: Fixed wrongly displayed message about firmware mismatch
* **OPAL-RT Board**: Fixed wrongly found hardware mismatch for extra slot of OP4810-IO/OP4815-IO platforms
* **OPAL-RT Board**: Fixed validation of threshold limits for digital channels
* **I/O interface synchronisation**: Fixed logs that were referencing the wrong network interface used by the Oregano card

### Breaking changes

* Unused G\_Ref and P\_Ref sensors on Network FACTS and HVDC LCC pulse components were removed.
* **Dasboard**: The Edit mode for panels is now a single button, and the mode is indicated by a dotted grid. Edit mode can also be triggered with the "E" shortcut.
* **Dasboard**: The internal data zip file of a Dashboard project is now a folder, allowing independent versioning.
* **Dasboard**: The deletion modal for the tab group widget no longer appears if the "Always display confirmation modal when deleting blocks" preference is unchecked.
* **Dasboard**: Removed the default lower and upper limit colors in the gauge widget.

### Known issues

N/A

***

## Version: 2024.3

### New features

* Importing Power Factory models to HYPERSIM is now possible. See PowerFactory Network Import for more details.
* Support Matlab 2024a.
* ScopeView now features a new tool for combining signals from multiple COMTRADE files.
* A new option has been added to the Sensor Management to disable I/Os during the simulation without removing sensor connections.
* The HyWorksApi Commands python API now proposes two additional functions:
  * setComponentParameters and getComponentParameters to set and get multi-parameters at a glance.
  * getLoadFlowReport
* Introduction of the Control Smart Inverter library designed to meet the requirements of IEEE Std. 1547-2018. This library includes control modules for both grid-forming and grid-following converters.
* Introduction of three Control Exciter system models:
  * The AC6A is used to represent field-controlled alternator-rectifier excitation systems with system-supplied electronic voltage regulators
  * The ESST4B excitation system in which is applied a low-pass filter to the terminal voltage transducer output, EC.
  * The IEEEX1
* Introduction of three Control Governors models:
  * The DEGOV model used to simulate a Woodward diesel generator governor.
  * The IEEEG1 model used to simulate a steam turbine-governor.
  * The GGOV1 model used to simulate a natural gas turbine-governor.
  * The IEESGO model used to simulate a steam turbine model improved in 1973 from the TGOV1 model from IEEE.
* Introduction of a Control Stabilizer:
  * The IEEEST model based on the PowerSystem Stabilizer (PSS) IEEEST.
* An additional Network Source has been developed:
  * AC Voltage Source with Impedance
* Three new example models have been added:
  * Example FPGA-Based Frequency Dependent Line
  * Example PowerFactory Import 39-Bus New England System
  * Example FPGA-Based Multirate stubline for HYPERSIM/eHS
* **Custom Network Import**: Added explanation in Unified Database Documentation on how to add user-defined HYPERSIM libraries in a user-defined import
* **IEC 60870-5-104 slave**: Added support for time-tagged write commands for normalized, scaled and floating point measurands.
* **OPAL-RT Board**: Added support for the standard I/O type H module OP48H20, for the OP4810-IO/OP4815-IO expansions chassis.
* **MODBUS master**: Added support for the MOXA CP-116E-A and CP-118EL-A cards in RTU mode.
* **MODBUS slave**: Added support for the MOXA CP-116E-A and CP-118EL-A cards in RTU mode.
* **EXata CPS - Communication Network Toolbox**: A new UI has been added to configure EXata CPS with HYPERSIM. Accessible within the Simulation Settings, this UI allows users to conveniently select their preferred version of EXata to run. Additionally, users can choose to start simulations with either a JSON or configuration file. EXata CPS 1.1 is not compatible with the new UI. Only EXata CPS 8.1.3, the latest version, is compatible with the new UI in HYPERSIM. This updated version includes many changes from EXata CPS 1.1, with significant improvements in configuring packet modification (MODP) attacks.

### Improvements

* Improved Scopeview | Comtrade Combiner to add a warning when a file will be overwritten during generation.
* A new documentation page Dashboards Troubleshooting is available to describe common issues with Dashboards.
* Added a warning when using Dashboards with a target that do not use automatic network configuration.
* Improved LoadFlow UI

### Bug fixes

* Fixes UI freeze in the Sequencer User Interface when the script doesn’t end properly (for example with an endless loop).
* Fixed the PSS4B help button not linking to the correct documentation page.
* Fixed an issue preventing one to deselect a sensor during a simulation.
* **PSSe Network Import**: Fixed an error when connecting machine controllers using bundles using csc blocks
* **OPAL-RT Board**: Fixed reload of bitstreams on SGI systems
* **OPAL-RT Board**: Fixed loss of communication with FPGA after an OP4810-IO/OP4815-IO reboot
* **OPAL-RT Board**: Fixed crashes during bitstream programming.
* **OPAL-RT Board**: Fixed the FPGA application crashed detection mechanism which was reporting errors even for successful simulations.
* **OPAL-RT Board**: Fixed missing UI field that permits control of the phase shift of PWM output signals in real-time.
* **TCP-UDP**: Fixed configuration errors when multiple streams configured with the same NIC had explicited the same NIC speed.

### Breaking changes

* **PSSe Network Import**: Changed following blocks import to use HYPERSIM native component instead of UCMs
  * IEEEX1
  * IEEST
  * ESST4B
* **PSSe Network Import**: Changed minimum Voltage Source RLC parameters values
* **PSSe Network Import**: Changed default values for Vuel and Voel when importing AC1A

### Known issues

N/A

***

## Version: 2024.2

{% hint style="info" %}
The 2024.2 version was not officially released, and all of its feature are therefore released within the 2024.3 version.
{% endhint %}

### New features

* A new example model on Frequency Dependant Line Example FPGA-Based Frequency Dependent Line
* The 'Help & Support' page now includes a new 'Contact Support' button.
* A new search bar is now available on the 'Options' page for quickly filtering example models.
* ScopeView now features a new tool for combining signals from multiple COMTRADE files.
* A new tool is now available to upgrade old recording files (.oprec) to the latest version of the OPREC format
* A new tool is now available in Topology Analysis to locate fragmented signals, which occur when signals have multiple segments (e.g., when using Page Connectors).
* A new example model on FPGA-Based Frequency Dependent Line (FD-Line) is now available.
* Control measurements now include a new Root Mean Square (RMS) component with three phases support.
* **PSCAD Network Import**: Added PSCAD time step setting support
* **PSCAD Network Import**: Added controlled parameters for COMPLEX UCM
* **PSCAD Network Import**: Added support of DiagonalWires
* **IEC 61850**: Added support for parsing AccessPoint references.
* **Modbus Slave**: Added support for the unit ID feature in TCP mode.
* **OPAL-RT Board**: Added support for OP4810-IO and OP4815-IO expansion chassis based on AMD Versal FPGA technology.
* **OPAL-RT Board**: Added support for the OP5367-6 mezzanine.
* **OPAL-RT Board**: Added a check in case the application crashed during execution.
* **OPC UA Server**: Added support for IP aliasing.
* **EXata CPS - Communication Network Toolbox**: Added UI to configure EXata CPS with HYPERSIM,

### Improvements

* The FPGA Scope workflow has been greatly improved by allowing signals to be selected directly in ScopeView.
* The search bar for finding devices can now ignore capitalization when searching. It now also finds devices by name by default.
* Signal Generator now validates files before execution to detect and prevent the use of corrupted files.
* The Topology Analysis report has been improved to enhance the user experience.
* Many overall improvements have been added to the “Help & Support” page.
* Updated the Cyber-Physical example model to support EXata CPS 8.1.3. Examples Cyber-Physical Simulation of a Microgrid Subject to Cyber-Attacks
* HYPERSIM installation on a target is now prevented if a simulation is currently running there
* Added support for tabulations in C code blocks
* **Data Logger Python API**: The SignalGroupInfo object has been updated to simplify its usage
  * get\_id() method is now deprecated and will be removed from the next release.
  * get\_filename() method is now deprecated and will be removed from the next release.
  * get\_port() method is now deprecated and will be removed from the next release.
  * the representation (**repr**) of a SignalGroupInfo object has been modified to hide internal and irrelevant data. No code should rely on this representation.
* **Data Logger Python API**: The connection to a SignalGroup has been updated to simplify its usage
  * connection with ip and port number is now deprecated and will be removed from the next release.
  * it is now encouraged to directly provide a SignalGroupInfo object to connect to a SignalGroup. This will be the only way to connect to a SignalGroup in the next release.

### Bug fixes

* Resolved an issue where the pages identifier was lost after wrapping components into a sub-circuit.
* Addressed a bug causing HYPERSIM to still open when the license expiration date is the current date.
* Updated the installation process to allow a fresh installation on a target without a license.
* Fixed an issue triggering an error popup when setting a text parameter to a blank value, even though the parameter was set.
* Resolved an issue where HYPERSIM would not start correctly with SentinelOne antivirus program.
* Fixed a bug where the signal in 1-ph CP line would be visually shown as a 3-phase signal.
* **IEC 61850**: Fixed configuration revision parameter in Sample Value messages.
* **IEC 61850**: Fixed loss of connections for Sample Value messages when updating the SCL file they were extracted from.
* **IEC 61850**: Fixed duplication of data points appearing after parsing certain SCL files.
* **IEC 61850**: Fixed GOOSE header parameter numDataSetEntries to respect the number of data set elements.
* **Modebus Slave**: Fixed feature of writing multiple coils.
* **Modebus Slave**: Fixed simulation load failure when only one 32-bit integer data is configured.
* **Modebus Slave**: Fixed faulty byte ordering of integers that always defaulted to BADC.
* **Modebus Slave**: Fixed simulation load failure due to excessive log messages when the interface was configured in verbose mode.
* **OPAL-RT Board**: Fixed chassis description for OP5705IO and OP5705XG in the ‘Chassis type’ drop-down.
* **OPAL-RT Board**: Fixed voltage output and threshold configurability for bi-directional cards.
* **TCP-UDP**: Fixed automatic EXata file transmission to the simulator.

### Known issues

N/A

***

## Version: 2024.1.4

### Bug fixes

* Fixed HYPERSIM installer missing ActivationTool

***

## Version: 2024.1.3

### New features

**I/O Interfaces**: Added support for slot types C and D mezzanine.

***

## Version: 2024.1

### New features

* Added support for MATLAB R2023b
* Added a “format” column in the sensor view that displays the format of a signal value such as “double” or “int”
* Added a Diagnostic Button in the Help section that gathers relevant log files into a ZIP archive
* Added numbered prefixes for coefficients in the mask of Transfer Functions
* Added a warning upon opening OPAL-RT dashboards when the network configuration of the target does not support usage of graph widgets
* Added an option in the Preferences menu to automatically add missing targets when opening a model
* Added an option to save a license request into a JSON or TXT file allowing one to manually send it later in case the license server is not reachable
* **Dashboard**: Added a new “Shape” widget which allows to create simple shapes such as triangles or rectangles
* **Dashboard**: Added support for vector data points in both table and tree views. Support their connections in the data points picker
* **PSCAD Network Import**: Added partial support of dynamic datatap (only constant controlled dynamic datataps are now supported)
* **PSSE Network Import**: Added support for PSSE v35
* **PSSE Network Import**: Added support for new components:
  * Gas turbine governor (GAST)
  * SEXS
* **Modbus Slave**: Added an option to allow read/write operations on multiple coils and registers even if there are gaps between the address ranges

### Improvements

* Improved default folder paths when opening a new example model or license file, or importing network files, or creating new UCM
* Improved ScopeView to suggest the current model folder when opening a template
* Improved error popup when the HyCore or HyServer services from a previous release are already running
* Improved workflow to avoid modifying the network configuration of a target while a simulation is running
* Improved RT Monitor documentation with a diagram explaining the different performance measurements of a simulation
* Improved disk space report in target diagnostic
* Improved sub-circuit form creation by simplifying and clarifying the workflow to expose parameters
* Improved target services (HyCore/HyServer) to use systemd instead of init.d to improve network interface initialization on OPAL-RTLinux
* **Test automation**: Improved the documentation describing how to set up a working Python environment
* **Test automation**: Improved Sequence Manager workflow with the selected theme now being applied to all tabs
* **Dashboard**: Improved sensor synchronization between Dashboard and HYPERSIM. Using “Fetch data” is no longer required when adding and removing sensors
* **Dashboard**: Improved the synchronization of the project’s state to avoid issues where Dashboard was sometime seeing a running simulation as stopped
* **Dashboard**: Improved the stability of the graph widget while a simulation is running
* **Dashboard**: Improved the data point picker user experience when modifying connections
* **Dashboard**: Improved error messages when adding connections
* **Dashboard**: Improved the sidebar to make it hidden by default and open automatically when a block is selected
* **Dashboard**: Improved resizing blocks with 8 handles by preserving the x/y ratio only when the shift key is pressed
* **Dashboard**: Improved the auto scale of graphes by excluding hidden signals from the scale computation
* **Dashboard**: Improved consistency by scaling the graph widget with respect to the size of the diagram
* **PSCAD Network Import**: Improved the HYPERSIM console display of non-mapped components during import
* **PSCAD Network Import**: Improved import logs with simplified information
* **PSSE Network Import**: Improved the HYPERSIM console display of non-mapped components during import
* **PSSE Network Import**: Improved import logs with simplified information
* **PSSE Network Import**: Improved load flow handling through replacing Sbase with Pgen of machine for the base power of the ideal transformer when machines are connected on the same bus
* **PSSE Network Import**: Improved the descriptions of the import options

### Bug fixes

* Fixed the target manager main table Active status that was only updating the target status when restarting HYPERSIM
* Fixed the progress bar widget sometimes not being scaled to the correct size when multiple tasks are in progress
* Fixed the RT Monitor view that was not updating the CPU list correctly when topology changes happen
* Fixed the sensor summary “full view” not displaying all columns
* Fixed the Target Manager view that froze when one target in the list was not accessible
* Fixed the automatic recompilation of the model when a compiler flag in simulation settings was modified
* Fixed the datalogger tool that was not recording some signals when using a trigger
* Fixed the datalogger tool that was not recording when a sensor was deselected
* Fixed the datalogger live acquisition that was not working properly after a restart of the simulation
* Fixed the save button of UCM Builder that was sometimes incorrectly greyed out
* Fixed the UCM Builder that was not saving properly a new UCM file unless the “File → New” menu was used beforehand
* Fixed the Line Generator tab of the Line component form that was not calculating any parameters
* **Test automation**: Fixed “displayComponent” and “displayConnections” Python API commands that were no longer working correctly
* **Dashboard**: Fixed and re-enabled the Onboarding tour
* **Dashboard**: Fixed minor widget rotation bugs
* **Dashboard**: Fixed an issue where Dashboards would randomly freeze after resizing columns
* **Dashboard**: Fixed an issue where the order of graph signal colors was lost after a copy and paste
* **Dashboard**: Fixed issue where the graph widget would sometime miss the trigger condition
* **Dashboard**: Fixed horizontal shifting of the graph widget with a specific configuration
* **PSCAD Network Import**: Fixed the import of models containing Multiply components with different input sizes
* **PSCAD Network Import**: Fixed an issue when importing multiple signals having the same name but different letter cases under the same level of a PSCAD model
* **PSCAD Network Import**: Fixed import of the Hard Limiter component not working properly when only one controlled limit was set
* **PSSE Network Import**: Fixed division-by-zero issue when P=Q=0 for Switched Shunts
* **PSSE Network Import**: Fixed issue when machine controls were not properly excluded when their associated machines were excluded

### Breaking changes

* Removed redundant datalogger buttons from the top right toolbars of ScopeView
* Removed the obsolete <support@opal-rt.com> email address from some error messages
* **PSSE Network Import**: Removed Pref from HYGOV import

### Known issues

N/A


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/hypersim/readme/release-notes-2024.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
