Integrating Web Author with AI Positron Assistant Enterprise

Configuring the Oxygen AI Positron Assistant Enterprise for Web Author Plugin

1. Go to your Administration Page.
2. Select Plugins.

3. Click the Configure icon next to the Oxygen AI Positron Assistant Enterprise for Web Author plugin to open the Plugin configuration dialog box.

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

   AI Connector

   Specifies the connector type: OpenAI, Microsoft Azure OpenAI or Anthropic Claude.

   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.

   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.

   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 you do not specify an API key, the plugin will try to use system properties to authenticate using Microsoft Entra ID.

   To use this method, you must 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).

   The connector supports these authentication methods:

   Service principal authentication using a client secret

   For this type of authentication, create a client secret and set these 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.

   Service principal authentication using a client certificate

   For this type of authentication, set up a certificate and set these 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 of a PFX/PEM certificate file
   AZURE_CLIENT_CERTIFICATE_PASSWORD	Password for a PFX/PEM certificate

   Username and password authentication

   For username and password authentication, set these 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_USERNAME	A username (usually an email address).
   AZURE_PASSWORD	The associated password for the given username.

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

   Vision-specific Settings

   Vision-specific settings are only used when images are attached in the Chat panel or sent to the AI engine with specific actions (e.g. Generate Documentation Draft).

   Vision - Endpoint

   Optional Azure AI deployment endpoint that can analyze images using Vision. This setting specifies 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/.

   Vision - Deployment

   Optional deployment name that was chosen when the Vision model was deployed in Microsoft Azure.

   Vision - API key

   Optional Microsoft Azure OpenAI Service for the endpoint that can analyze images using Vision.

   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.

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

   Context

   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.

   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.

6. 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 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.

7. Click Apply.

Function Calls

Within the definition of custom actions, you can reference existing functions 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 function 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.
• 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_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.

• 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.