Edit online

Preferences (Enterprise)

Oxygen AI Positron Assistant Preferences

Various settings can be configured in Options > Preferences > Plugins > Oxygen AI Positron Assistant:
Enable AI Positron Assistant
Deselect this setting to disable the AI assistant. Combined with the Project Options radio button, you can disable the AI assistant for certain projects.
Context prompt
The context provides useful information about the user to the AI and is used in each action and chat request to create more relevant and personalized responses.
Additional context file
The content of this referenced file is added to the Context value and used in all AI action prompts. The file path reference can contain editor variables.
Allow automatic validation and correction of AI-generated content
When enabled (default), AI-generated content is automatically validated when you insert it into a document or after the AI saves it to a file. If errors are detected, the AI automatically tries to provide a corrected version of the generated content.
Note:
The AI will not be able to find solutions for certain types of errors, so some manual corrections will still be required.

AI Service Configuration Preferences

Various service-related connection settings can be configured in Options > Preferences > Plugins > Oxygen AI Positron Assistant (Enterprise) > AI Service Configuration:
Tip:
You can use editor variables such as ${env(ENV_NAME)} in all configuration and header parameter values.
AI Connector
Specifies the connector type. The default options are: OpenAI, Microsoft Azure OpenAI, Anthropic Claude, or Google Gemini.

OpenAI:

If OpenAI is chosen as the connector type, the following settings are available:

Address
The web address of the OpenAI service. By default: https://api.openai.com.
API key
The OpenAI API key necessary to work with the connector.
Note:
This option does not get saved in the Project-level options.
Organization ID
For users who belong to multiple organizations, they can specify which organization is used for an API request. Usage from these API requests will count as usage for the specified organization.
Default model
The default model is used for the chat view and for actions that do not explicitly specify a model.
Enable text moderation
This setting applies moderation (checks whether content complies with OpenAI's usage policies) to both the input text sent to the AI service and the response received from the AI service. It is enabled by default.
Tip:

By default, when executing an action using the OpenAI connector, three requests are made:

Enable speech-to-text
This setting allows for speech-to-prompt transcribing using the AI engine. If enabled, the Start recording prompt using the microphone button should be displayed under the chat box (in the AI Positron Assistant view).
Enable streaming
This option controls whether streaming is enabled. When enabled (default), AI-generated answers are delivered in real time as a continuous flow. If disabled, the complete answer is delivered all at once after the processing is finished.
Extra Headers
Extra name/value parameters to set in the headers that are specific for the AI requests.
Tip:
If the service uses Bearer Authentication, you can specify the key in the Key text field. If another authentication method is used, the Key field can be left empty, and the Extra Headers table can be used to set the authentication info on the request header. Note that editor variables can be used in this field and you can set your key in editor variables and specify the value in this table like this: ${env(AI_SERVICE_KEY)} to access pre-set values of environmental variables.
Notes:
  • You can use your own fine-tuned OpenAI models.
  • The OpenAI connector might work with other AI engines that use the OpenAI APIs (like Grok or Deepseek).

MS Azure OpenAI:

If Microsoft Azure OpenAI is chosen as the connector type, the following settings are available:

Endpoint
The web address where the connector service is located. This value can be found in the Keys & Endpoint section when examining your resource from the Azure portal. For example: https://your-company-name.openai.azure.com/.
Deployment
The deployment name that was chosen when the model was deployed in Microsoft Azure.
API key

The Microsoft Azure OpenAI Service key necessary to work with the connector.

If an API key is not provided, the application will attempt to authenticate with Microsoft Entra ID by using one of the supported identity-based methods.

Enable streaming
This option controls whether streaming is enabled. When enabled (default), AI-generated answers are delivered in real time as a continuous flow. If disabled, the complete answer is delivered all at once after the processing is finished.
Extra Headers
Extra name/value parameters to set in the headers that are specific for the AI requests.
Speech service region
If a speech service is configured in the MS Azure account, you can use this setting to set the region of the server (for example: eastus). As an alternative, you can set a SPEECH_REGION environmental variable. Once the speech service is configured, the Start recording prompt using the microphone button should be displayed under the chat box (in the AI Positron Assistant view). This button allows for speech-to-prompt transcribing using the AI engine.
Speech service key
If a speech service is configured in the MS Azure account, you can use this setting to set the key to be used with the service. As an alternative, you can set a SPEECH_KEY environmental variable.
Note:
You can use your own fine-tuned Microsoft Azure OpenAI models.
User-based Authentication for Microsoft Azure:
The Microsoft Azure OpenAI connector supports the following identity-based authentication flows:
OAuth 2.0 Authorization Code Flow (User Sign-in)

This method enables interactive user sign-in via a browser. It is recommended for desktop applications used by individual users with personal or work accounts.

When a user triggers an AI action and is not authenticated, the application displays a dialog box prompting them to sign in using their Microsoft account. Upon successful login, the application retrieves an access token and continues operation.

Required Environment Variables to configure authentication flow:

Variable Description
AZURE_OAUTH_TENANT_ID Microsoft Entra (AAD) Tenant ID.
AZURE_OAUTH_CLIENT_ID Application (client) ID.
AZURE_OAUTH_REDIRECT_URI Redirect URI configured in the Entra app.
Note:
You must register an application in Microsoft Entra ID that includes the specified redirect URI. The signed-in user must also be assigned a role that allows access to the Azure OpenAI service (e.g. Cognitive Services OpenAI User).
Service Principal Authentication

Service principal authentication is ideal for non-interactive scenarios, such as background processes or automation scripts.

Choose one of the options below if you need to authenticate without prompting the user to sign in.

Before you begin, create a service principal and assign a role to it that allows access to the Azure OpenAI service (e.g. the Cognitive Services OpenAI User role).

  • Client Secret

    Use this method for simpler setups in trusted environments.

    Be aware that on desktop systems, secrets stored in environment variables or config files are not encrypted by default and may be exposed to other local users or processes.

    Required Environment Variables:

    Variable name Value
    AZURE_CLIENT_ID ID of a Microsoft Entra application.
    AZURE_TENANT_ID ID of the application's Microsoft Entra tenant.
    AZURE_CLIENT_SECRET One of the application's client secrets.

  • Client Certificate

    Use this method in high-security environments where certificate-based authentication is preferred over storing client secrets.

    Be aware that certificate files, like other secrets, must be protected properly—especially on desktop systems where local users may gain access to file contents if not secured appropriately.

    Required Environment Variables:

    Variable name Value
    AZURE_CLIENT_ID ID of a Microsoft Entra application.
    AZURE_TENANT_ID ID of the application's Microsoft Entra tenant.
    AZURE_CLIENT_CERTIFICATE_PATH Path to the PEM or PFX certificate file.
    AZURE_CLIENT_CERTIFICATE_PASSWORD Password for the certificate file (if any).

The connector will automatically detect and use the correct authentication flow based on which environment variables you have configured.

Note:
Oxygen XML should be restarted after each environment-variable change for the changes to take effect.

Anthropic Claude:

If Anthropic Claude is chosen as the connector type, the following settings are available:

Endpoint
The web address where the connector service is located. By default, it is https://api.anthropic.com/.
API key
The Anthropic Claude API key necessary to work with the connector.
Model
The Anthropic Claude model to use. By default, it is claude-3-opus-20240229.
Enable streaming
This option controls whether streaming is enabled. When enabled (default), AI-generated answers are delivered in real time as a continuous flow. If disabled, the complete answer is delivered all at once after the processing is finished.
Extra Headers
Extra name/value parameters to set in the headers that are specific for the AI requests.

Google Gemini:

If Google Gemini is chosen as the connector type, the following settings are available:

Address
The web address where the connector service is located. By default, it is https://generativelanguage.googleapis.com/.
API Key
The API key that can be generated in Google AI Studio: https://aistudio.google.com/app/apikey.
Model
The Gemini model to use (the available models can be found at https://ai.google.dev/gemini-api/docs/models).

Custom AI Service:

This connector is available by installing the Oxygen AI Positron Custom Connector Add-on. It allows a connection to a custom AI service that exposes a REST API, similar to OpenAI's chat-completion API. Unlike the built-in Open AI connector, this add-on supports the OAuth Client Credentials Flow for authentication and offers more flexibility by letting you set query parameters.

Vertex AI Service:

This connector is available by installing the Oxygen AI Positron Vertex AI Connector Add-on. It enables integration with Google Cloud's Vertex AI platform.

Actions Preferences

Various settings related to AI actions can be configured in Options > Preferences > Plugins > Oxygen AI Positron Assistant > Actions:

Load default actions
Specifies if default actions are loaded.
Additional actions folder
You can use this option to specify a local folder where you have stored additional actions.
Actions to exclude
You can specify a comma-separated list of IDs for the actions that you do not want presented in the list of available actions. Use the menu to the right of the text field to choose the actions to exclude.
Embed AI Assistant in Author page
Controls whether or not the AI Positron Assistant drop-down widget is displayed when documents are open in the Author visual editing mode. This drop-down list contains some of the most useful AI actions for creating and improving the structure and content of the current document.

Saved Memories Preferences

Enable memory store
A setting used to disable the user-specific memory store that contains rules stored by the AI engine for the current user. It is enabled by default.
Memory store text area
A text area that contains the set of rules stored by the AI engine for the current user. The text area is fully editable. All the rules from this text area are gathered and used along with the Context when any AI action is invoked or when chatting with the AI engine.

Functions and RAG Preferences

Various settings related to the use of functions for retrieval augmented generation can be configured in the Retrieval-Augmented Generation (RAG) preferences page (click the Settings button in the header and go to Retrieval-Augmented Generation (RAG)).
Enable functions
Enables the use of functions for retrieval-augmented generation and for writing content in the project.
Enable project-based RAG
Enables retrieval-augmented generation based on similar content obtained from the current open project. Actions and chat interactions generate content give more precise and meaningful responses when this setting is enabled. It is enabled by default. The available functions used for RAG are listed in the text box.
The AI actions that use RAG are:
  • Generate Documentation Draft
  • New DITA Topic
  • Expand Draft
  • Create Topics
Ask for confirmation
When selected (default), the end user is asked to confirm whenever each specific project-based RAG function is about to be processed.
Content retrieval token limit
Specifies a limitation for the upper amount of project content that may be sent to the AI engine to enhance responses and tune them based on the currently open project.
Enable external RAG sources
Enables the use of external retrieval augmented generation sources.
Oxygen Feedback site token

When the Oxygen Feedback product is used to provide search functionality for a web site generated from the DITA XML project, its search system can be used to retrieve related content. In the Oxygen Feedback administrative interface, find the installation instructions for the site version that you want to use (click the Installation button on your version's tile in the Site Version page). The installation information contains a unique deploymentToken value that can be copied and pasted into the Oxygen Feedback site token field.

Oxygen Feedback site description
A description for this external content retrieval site that is passed to the AI engine to help it decide whether or not the external source is used.
Enable writing content in project
Allows functions that can be used by the AI to write content in the current project. The available functions used for this purpose are listed in the text box.
Limit read/write access to
Allows you to restrict the locations where functions can read and write content. You can specify these locations as a comma-separated list of resource paths. By default, read and write access is restricted to the project directory and the directory of the current root map.

XPath Functions Preferences

Enable XPath Functions
Enables the use of AI-specific XPath functions in Oxygen when applying Schematron validation or XSLT transformations.
Cache responses and reuse them for identical prompts
If enabled (default), responses for identical requests are stored (cached), resulting in fewer requests being sent to the AI server and faster completion times. A Clear cache button located to the right of this option can be used to clear the cache.
Cache size
Specifies a maximum limit for the cache size.
Notify me when the number of requests exceeds
You can select this option and specify a number of AI requests that when exceeded, a confirmation dialog box is displayed asking if you want to continue using the XPath AI functions. If you select "No" for the answer, the XPath functions will be disabled.