Edit online

Integrating Web Author with AI Positron Assistant Enterprise

The Oxygen XML Web Author server can include an Oxygen AI Positron Assistant Enterprise for Web Author plugin that provides the ability to use a specific AI engine for chat purposes or to run useful predefined actions. OpenAI, Microsoft Azure OpenAI, Anthropic Claude, and Google Gemini are provided as default configuration options, but you can also connect to Google's Vertex AI Service by installing the Oxygen AI Positron Vertex AI Connector Add-on for Web Author or you can configure a custom service by installing the Oxygen AI Positron Custom Connector Add-on for Web Author.

You can download the plugin from here: Web Author AI Positron Assistant Plugin Download. The AI Positron Assistant is also currently accessible to try on our online demo website.

You can then install the plugin in the Web Author or Content Fusion server to make the AI Positron Assistant side-pane accessible.

Important:

If you are an integrator using the Web Author Component in your own solution, you need to contact us to discuss the plugin's availability and licensing.
The AI Positron Assistant side-pane appears in the UI only if it is properly licensed and configured by an administrator.

The connection details to the AI engine can be configured by following the steps below.

Configuring the Oxygen AI Positron Assistant Enterprise for Web Author Plugin

Go to your Administration Page.
Select Plugins.
Click the Configure icon next to the Oxygen AI Positron Assistant Enterprise for Web Author plugin to open the Plugin configuration dialog box.

In the AI Service tab, specify the connector and configure the necessary details:

AI Connector: Specifies the connector type: OpenAI, Microsoft Azure OpenAI, Anthropic Claude, or Google Gemini.

OpenAI:

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

Base URL

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.

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:

A moderation on input content request to configured_web_address/v1/moderations.
A completion request to configured_web_address/v1/chat/completions.
A moderation on content returned by AI to configured_web_address/v1/moderations.

If your AI service does not require moderation (for example, moderation is already made by chat/completions endpoint) you can disable it by unchecking this checkbox.

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:

Base URL: 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 listed below.

Identity-based Authentication for Microsoft Azure:

The Microsoft Azure OpenAI connector supports the following identity-based authentication flows:

Service Principal Authentication

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.

Required System Properties :


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.

Required System Properties:


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 system properties you have configured.

Note:

Oxygen XML Web Author should be restarted after each system-property change for the changes to take effect.

Anthropic Claude:

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

Base URL: 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: Use this drop-down to select the Anthropic Claude model.

Google Gemini:

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

Base URL: 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 for Web Author. 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 for Web Author. It enables integration with Google Cloud's Vertex AI platform.

Optionally, you can configure a context and additional actions in the Preferences tab:

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.

Actions

Load default actions

Specifies if default actions are loaded.

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 and if validation problems are detected, the content is re-sent to the AI in a feedback loop to fix the content generation problems.

Additional actions

You can use this option to specify a zip file that contains the additional actions configured in JSON files. Use the Upload actions button to upload the specified zip file. If a file has already been uploaded, it will be replaced with the new one. You can use the Remove actions button to remove the currently uploaded additional actions.

Actions filter

You can deselect any of the actions that you do not want presented in the list of available actions. Then, click the Apply button to save your changes.
The RAG preferences page allows configuring settings related to retrieval augmented generation.

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.
Important:
Functionality for this issue is currently a work in progress and may depend on the CMS integration.

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

Enable 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 if the external source is used or not.

Enable writing content in project (Experimental)

Allows tools that can be used by the AI to write content in the current project. The available tools used for this purpose are listed in the text box.
Click Apply.

Custom Actions

It is possible to create additional custom actions by defining them in a zipped JSON file and attaching it within the Administration page.

Create a JSON file that contains the custom actions based on information found in Oxygen AI Positron Assistant: Creating Custom Actions.
Zip the created file.
Go to the Administration Page and to the Preferences tab. In the Actions section, specify your zip file in the Additional actions option and use the Upload actions button to upload it. If a file has already been uploaded, it will be replaced with the new one.
Click Apply before exiting the Administration Page.

Custom actions can also be distributed by being bundled with existing plugins or frameworks.

Tool Calls

Within the definition of custom actions, you can reference existing tools that are called by the AI engine to interact with the application. This gives actions more context information and generates more accurate responses from the AI.

The current available tool reference values are:

get_current_document_plain_text_content - Retrieves all plain text (e.g. without markup) from the current document open in the editor.
get_current_document_marked_up_content - Retrieves all text with markup from the current document open in the editor. An optional lineNumbering parameter allows the AI to request the returned content to be returned with line numbers included.
get_content_around_caret - Retrieves size-limited content around the current cursor location within the document open in the editor.
get_related_content_from_webhelp - Returns content from the associated Oxygen Feedback WebHelp system that a token has been configured for, in the Web Author AI Positron preferences administration page.
get_related_content_from_specific_feedback_site - Returns content from the specified Oxygen Feedback WebHelp system token passed as a parameter.
get_current_editor_file_location - Retrieves the location (absolute path/URL) of the current file that is open in the editor.
get_content_for_document_url - Retrieves the entire content for a document with a specific URL. An optional lineNumbering parameter allows the AI to request the returned content to be returned with line numbers included.
save_document(URL,content) - Saves the document at the specified path and writes content to it. If a resource already exists at the specified URL, the content of the document will be overridden with the new content.

Also, in new chat sessions, the AI has access to content around the cursor location within the document open in the editor.

Extending Functionality Using Plugins

The Oxygen AI Positron Assistant Enterprise plugin offers advanced options for developers to extend its functionality. Below is an overview of the main extension points available:

AI Connectors Extension

This extension point lets developers build a plugin that adds an AI connector to the Oxygen AI Positron Assistant Enterprise. It enables connections with AI providers not covered by our built-in options.

To create a connector, follow these steps:

Add oxygen-ai-positron-api as a dependency in your plugin project.
Implement the ro.sync.exml.plugin.ai.AIConnectorsPluginExtension interface in your plugin's libraries.
In the plugin descriptor file, define the <extension> element that points to the implementation of your classes:
```
<extension type="AIConnectors" class="my.pack.CustomAIConnectorsProviderPluginExtension"/>
```

A sample plugin is available to demonstrate how to add a connector to a custom AI service that exposes a REST API for OpenAI chat completions.

Note:

The AIConnectors extension type can be implemented starting with version 27.1 of Oxygen XML Web Author

AI Tools Extension

The AI Tools extension point lets developers add their own custom callback tools or replace the built-in ones. This makes it possible to create custom interactions with AI engines.

To implement a tool, follow these steps:

Implement the ro.sync.exml.plugin.ai.AIFunctionsPluginExtension interface in your plugin's libraries.
In the plugin descriptor file, define the <extension> element that points to the implementation of your classes:
```
<extension type="AIFunctions" class="my.pack.CustomAIFunctionsProviderPluginExtension"/>
```

Note:

The AIFunctions extension point can be implemented starting with version 27.0 of Oxygen XML Web Author

Distributing and Filtering AI Actions

When installed in Oxygen XML Web Author 27.1 or newer, plugins or frameworks can contain a folder named ai-positron-actions where custom AI actions are automatically loaded from by the AI Positron plugin.

The ai-positron-actions folder can contain an extra file named excluded-action-ids.txt, which can list all action IDs (on a line-by-line basis) that should be filtered out of the AI Positron UI.