Knowledge Discovery

Answer Server

Software Version 25.3

Administration Guide

Document Release Date: July 2025

Software Release Date: July 2025

Get Started With Answer Server

This section introduces OpenText Answer Server and describes how to install and run the server.

Introduction
Install and Set Up Answer Server
Configure Answer Server
Run Answer Server

Introduction

OpenText Answer Server uses Knowledge Discovery technology to provide specific and concise answers to user questions.

In a traditional Knowledge Discovery system, the user provides some search terms, or uses special search syntax, and the server returns a list of related documents. In Answer Server, the user specifies a question, and the server returns as specific an answer as possible.

The Answer Server has four types of system to answer different question types.

Answer Bank. The Answer Bank contains a store of reference questions and answers, which you can add and administer. When a user asks a question, the Answer Bank queries the store of existing questions for any that match, and returns the relevant answers. You can use an Answer Bank to maintain an FAQ list to answer questions such as:
- How do I fix my phone screen?
- What does error 404 mean?
- Can I use my phone to send photos of cats?
Fact Bank. The Fact Bank contains a store of factual information, to return simple factual answers. For example, you could use a Fact Bank to answer questions such as:
- What is the population of the USA?
- Who is the CEO of OpenText?
- What is the average June temperature in Antarctica?
Passage Extractor. The Passage Extractor links to a store of documents that contain general information that might be useful for answering questions (for example, your normal data index). When a user asks a question, the Passage Extractor queries the document store and attempts to extract short sentences or paragraphs that contain relevant answers. You can use a Passage Extractor to answer general questions that you do not have a fact store for, or that do not have a simple answer, such as:
- What is the tallest building in the world?
- What did the only repealed amendment to the US Constitution deal with?
- What is the weight of the Eiffel Tower?
RAG. The RAG (Retrieval Augmented Generation) module uses large language models (LLMs) to generate answers from documents in your system. When a user asks a question, the RAG module queries the document store and finds likely candidates for answers. It provides the original question and relevant content from these candidate documents in a prompt to an external LLM, which generates the answer.

The RAG module provides another approach to answering the same kind of general questions that you might answer with a Passage Extractor system.
Conversation. The Conversation module runs a real time conversation task with your end users. It allows you to set up an interactive virtual assistant to answer common user queries.

You can configure as many different versions of each system as you need. When you send a question to Answer Server, you can specify which of the configured systems you want to retrieve answers from.

The following sections describe the setup for these systems in more detail.

You can also configure Remote systems, which refer to an answer system on a separate Answer Server. In this case, you configure the system as normal on the remote Answer Server, and then configure a remote system in your main Answer Server. When you send a question to the main Answer Server, it can forward it to the remote systems. See Set Up a Remote Answer System.

Answer Server System Architecture

The following diagram shows the different components of the Answer Server system.

Answer Bank

The answer bank system uses a dedicated Agentstore component.

The Agentstore is a specially configured Content component that stores the set of questions and their answers. You can also create question equivalence classes, which store a set of equivalent questions that map to the same answer.

Fact Bank

The fact bank system consists of three pieces:

Fact Store (SQL database or Lua script). The fact store contains the factual information that you want to retrieve. Answer Server uses the parsed question and the associated entity and property codes to search the fact store for relevant facts. Usually the fact store component is a SQL database. Alternatively, you can use a Lua script to retrieve facts from an external fact store.
Question Parser (Named Entity Recognition). The fact bank uses a specialized Named Entity Recognition grammar to parse questions and extract the parts of the question that define the fact that the question requests. For example, for the question "what is the population of the USA", Named Entity Recognition determines that the user wants to find the population property of the USA entity. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Coding files. The coding files map entities, properties, and their synonyms to a unique code. Answer Server uses this code to retrieve data from the fact store. For example, the coding files can store the different ways of referring to the country USA as a single code (United States of America, US, and so on). The code can be easily retrieved to match to associated facts.

The fact bank system also includes additional Named Entity Recognition grammars for advanced time normalization. Advanced time normalization extracts dates and times in various formats from questions and normalize them to a consistent format, to improve fact retrieval.

Passage Extractor

A standard passage extractor system consists of two components:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
Passage Extractor Agentstore. The passage extractor uses Agentstore for some of the entity extraction operations. For example, you can set up agents that define people and place entities, and the passage extractor uses agent queries to extract those entities from the documents that you use to find answers. Agent matching is often quicker than Named Entity Recognition entity matching for simple entities that consist of fixed text, such as names.

The passage extractor also requires:

Named Entity Recognition grammars. The passage extractor uses the Question Parser Named Entity Recognition grammar, as well as grammars for extracting entities from passages that might contain answers, and for identifying sentences and paragraphs that might form legitimate answers, by using pattern matching. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Passage Extractor LLM

A passage extractor LLM system is an alternative to the standard system. Instead of using Knowledge Discovery entity extraction, the LLM system uses an LLM module to generate or extract answers from your data store. It generates an answer based on each candidate document that it finds, and returns the best answer from the set.

The LLM passage extractor requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module contains model files in a format that Answer Server can use to extract and generate your answers. This option uses third-party LLMs, which Answer Server downloads and uses. Alternatively, you can write a script to generate answers, for example from a different third-party LLM system.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Retrieval Augmented Generation

Retrieval Augmented Generation (RAG) is a method to combine the generative capabilities of large language models (LLMs) with a system to ensure that the answers generated are from a verifiable source. RAG finds answers in a body of data, and then uses the natural language generation of the LLM to create a human-readable answer.

The RAG answer system uses a similar approach to the passage extractor LLM system, with a prompt-based LLM to generate the answers from content that Answer Server retrieves from your data store. It can generate an answer from the content of multiple documents.

The RAG system requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module defines a script to use to generate the answers from a prompt, which Answer Server provides. The script can use third-party LLMs to generate answers from the prompt.
Prompt template. A template that Answer Server uses to create the prompt. This prompt template includes placeholder tokens that Answer Server replaces with the original user question, and the contextual data that Answer Server retrieves from your data store. The LLM can then use the question and contextual data to generate an answer.

Conversation

The conversation system does not have any required subcomponents. You configure conversation tasks by using a JSON configuration file, which describes the task, including:

introductory text.
the triggers to use to activate a particular conversation or option.
routing information to describe how to proceed through the conversation task, depending on user input.
details of lua scripts to run at particular points in the conversation to parse user input or provide more detailed conversation processing.

You can set your conversation triggers by using fixed phrases, regular expressions, or agents. If you want to use agents as triggers, you must configure an Agentstore component.

Introduction

OpenText Answer Server uses Knowledge Discovery technology to provide specific and concise answers to user questions.

The Answer Server has four types of system to answer different question types.

Answer Bank. The Answer Bank contains a store of reference questions and answers, which you can add and administer. When a user asks a question, the Answer Bank queries the store of existing questions for any that match, and returns the relevant answers. You can use an Answer Bank to maintain an FAQ list to answer questions such as:
- How do I fix my phone screen?
- What does error 404 mean?
- Can I use my phone to send photos of cats?
Fact Bank. The Fact Bank contains a store of factual information, to return simple factual answers. For example, you could use a Fact Bank to answer questions such as:
- What is the population of the USA?
- Who is the CEO of OpenText?
- What is the average June temperature in Antarctica?
Passage Extractor. The Passage Extractor links to a store of documents that contain general information that might be useful for answering questions (for example, your normal data index). When a user asks a question, the Passage Extractor queries the document store and attempts to extract short sentences or paragraphs that contain relevant answers. You can use a Passage Extractor to answer general questions that you do not have a fact store for, or that do not have a simple answer, such as:
- What is the tallest building in the world?
- What did the only repealed amendment to the US Constitution deal with?
- What is the weight of the Eiffel Tower?
RAG. The RAG (Retrieval Augmented Generation) module uses large language models (LLMs) to generate answers from documents in your system. When a user asks a question, the RAG module queries the document store and finds likely candidates for answers. It provides the original question and relevant content from these candidate documents in a prompt to an external LLM, which generates the answer.

The RAG module provides another approach to answering the same kind of general questions that you might answer with a Passage Extractor system.
Conversation. The Conversation module runs a real time conversation task with your end users. It allows you to set up an interactive virtual assistant to answer common user queries.

You can configure as many different versions of each system as you need. When you send a question to Answer Server, you can specify which of the configured systems you want to retrieve answers from.

The following sections describe the setup for these systems in more detail.

Answer Server System Architecture

The following diagram shows the different components of the Answer Server system.

Answer Bank

The answer bank system uses a dedicated Agentstore component.

Fact Bank

The fact bank system consists of three pieces:

Fact Store (SQL database or Lua script). The fact store contains the factual information that you want to retrieve. Answer Server uses the parsed question and the associated entity and property codes to search the fact store for relevant facts. Usually the fact store component is a SQL database. Alternatively, you can use a Lua script to retrieve facts from an external fact store.
Question Parser (Named Entity Recognition). The fact bank uses a specialized Named Entity Recognition grammar to parse questions and extract the parts of the question that define the fact that the question requests. For example, for the question "what is the population of the USA", Named Entity Recognition determines that the user wants to find the population property of the USA entity. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Coding files. The coding files map entities, properties, and their synonyms to a unique code. Answer Server uses this code to retrieve data from the fact store. For example, the coding files can store the different ways of referring to the country USA as a single code (United States of America, US, and so on). The code can be easily retrieved to match to associated facts.

Passage Extractor

A standard passage extractor system consists of two components:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
Passage Extractor Agentstore. The passage extractor uses Agentstore for some of the entity extraction operations. For example, you can set up agents that define people and place entities, and the passage extractor uses agent queries to extract those entities from the documents that you use to find answers. Agent matching is often quicker than Named Entity Recognition entity matching for simple entities that consist of fixed text, such as names.

The passage extractor also requires:

Named Entity Recognition grammars. The passage extractor uses the Question Parser Named Entity Recognition grammar, as well as grammars for extracting entities from passages that might contain answers, and for identifying sentences and paragraphs that might form legitimate answers, by using pattern matching. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Passage Extractor LLM

The LLM passage extractor requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module contains model files in a format that Answer Server can use to extract and generate your answers. This option uses third-party LLMs, which Answer Server downloads and uses. Alternatively, you can write a script to generate answers, for example from a different third-party LLM system.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Retrieval Augmented Generation

The RAG system requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module defines a script to use to generate the answers from a prompt, which Answer Server provides. The script can use third-party LLMs to generate answers from the prompt.
Prompt template. A template that Answer Server uses to create the prompt. This prompt template includes placeholder tokens that Answer Server replaces with the original user question, and the contextual data that Answer Server retrieves from your data store. The LLM can then use the question and contextual data to generate an answer.

Conversation

The conversation system does not have any required subcomponents. You configure conversation tasks by using a JSON configuration file, which describes the task, including:

introductory text.
the triggers to use to activate a particular conversation or option.
routing information to describe how to proceed through the conversation task, depending on user input.
details of lua scripts to run at particular points in the conversation to parse user input or provide more detailed conversation processing.

You can set your conversation triggers by using fixed phrases, regular expressions, or agents. If you want to use agents as triggers, you must configure an Agentstore component.

Introduction

OpenText Answer Server uses Knowledge Discovery technology to provide specific and concise answers to user questions.

The Answer Server has four types of system to answer different question types.

Answer Bank. The Answer Bank contains a store of reference questions and answers, which you can add and administer. When a user asks a question, the Answer Bank queries the store of existing questions for any that match, and returns the relevant answers. You can use an Answer Bank to maintain an FAQ list to answer questions such as:
- How do I fix my phone screen?
- What does error 404 mean?
- Can I use my phone to send photos of cats?
Fact Bank. The Fact Bank contains a store of factual information, to return simple factual answers. For example, you could use a Fact Bank to answer questions such as:
- What is the population of the USA?
- Who is the CEO of OpenText?
- What is the average June temperature in Antarctica?
Passage Extractor. The Passage Extractor links to a store of documents that contain general information that might be useful for answering questions (for example, your normal data index). When a user asks a question, the Passage Extractor queries the document store and attempts to extract short sentences or paragraphs that contain relevant answers. You can use a Passage Extractor to answer general questions that you do not have a fact store for, or that do not have a simple answer, such as:
- What is the tallest building in the world?
- What did the only repealed amendment to the US Constitution deal with?
- What is the weight of the Eiffel Tower?
RAG. The RAG (Retrieval Augmented Generation) module uses large language models (LLMs) to generate answers from documents in your system. When a user asks a question, the RAG module queries the document store and finds likely candidates for answers. It provides the original question and relevant content from these candidate documents in a prompt to an external LLM, which generates the answer.

The RAG module provides another approach to answering the same kind of general questions that you might answer with a Passage Extractor system.
Conversation. The Conversation module runs a real time conversation task with your end users. It allows you to set up an interactive virtual assistant to answer common user queries.

You can configure as many different versions of each system as you need. When you send a question to Answer Server, you can specify which of the configured systems you want to retrieve answers from.

The following sections describe the setup for these systems in more detail.

Answer Server System Architecture

The following diagram shows the different components of the Answer Server system.

Answer Bank

The answer bank system uses a dedicated Agentstore component.

Fact Bank

The fact bank system consists of three pieces:

Fact Store (SQL database or Lua script). The fact store contains the factual information that you want to retrieve. Answer Server uses the parsed question and the associated entity and property codes to search the fact store for relevant facts. Usually the fact store component is a SQL database. Alternatively, you can use a Lua script to retrieve facts from an external fact store.
Question Parser (Named Entity Recognition). The fact bank uses a specialized Named Entity Recognition grammar to parse questions and extract the parts of the question that define the fact that the question requests. For example, for the question "what is the population of the USA", Named Entity Recognition determines that the user wants to find the population property of the USA entity. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Coding files. The coding files map entities, properties, and their synonyms to a unique code. Answer Server uses this code to retrieve data from the fact store. For example, the coding files can store the different ways of referring to the country USA as a single code (United States of America, US, and so on). The code can be easily retrieved to match to associated facts.

Passage Extractor

A standard passage extractor system consists of two components:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
Passage Extractor Agentstore. The passage extractor uses Agentstore for some of the entity extraction operations. For example, you can set up agents that define people and place entities, and the passage extractor uses agent queries to extract those entities from the documents that you use to find answers. Agent matching is often quicker than Named Entity Recognition entity matching for simple entities that consist of fixed text, such as names.

The passage extractor also requires:

Named Entity Recognition grammars. The passage extractor uses the Question Parser Named Entity Recognition grammar, as well as grammars for extracting entities from passages that might contain answers, and for identifying sentences and paragraphs that might form legitimate answers, by using pattern matching. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Passage Extractor LLM

The LLM passage extractor requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module contains model files in a format that Answer Server can use to extract and generate your answers. This option uses third-party LLMs, which Answer Server downloads and uses. Alternatively, you can write a script to generate answers, for example from a different third-party LLM system.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Retrieval Augmented Generation

The RAG system requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module defines a script to use to generate the answers from a prompt, which Answer Server provides. The script can use third-party LLMs to generate answers from the prompt.
Prompt template. A template that Answer Server uses to create the prompt. This prompt template includes placeholder tokens that Answer Server replaces with the original user question, and the contextual data that Answer Server retrieves from your data store. The LLM can then use the question and contextual data to generate an answer.

Conversation

The conversation system does not have any required subcomponents. You configure conversation tasks by using a JSON configuration file, which describes the task, including:

introductory text.
the triggers to use to activate a particular conversation or option.
routing information to describe how to proceed through the conversation task, depending on user input.
details of lua scripts to run at particular points in the conversation to parse user input or provide more detailed conversation processing.

You can set your conversation triggers by using fixed phrases, regular expressions, or agents. If you want to use agents as triggers, you must configure an Agentstore component.

Introduction

OpenText Answer Server uses Knowledge Discovery technology to provide specific and concise answers to user questions.

The Answer Server has four types of system to answer different question types.

Answer Bank. The Answer Bank contains a store of reference questions and answers, which you can add and administer. When a user asks a question, the Answer Bank queries the store of existing questions for any that match, and returns the relevant answers. You can use an Answer Bank to maintain an FAQ list to answer questions such as:
- How do I fix my phone screen?
- What does error 404 mean?
- Can I use my phone to send photos of cats?
Fact Bank. The Fact Bank contains a store of factual information, to return simple factual answers. For example, you could use a Fact Bank to answer questions such as:
- What is the population of the USA?
- Who is the CEO of OpenText?
- What is the average June temperature in Antarctica?
Passage Extractor. The Passage Extractor links to a store of documents that contain general information that might be useful for answering questions (for example, your normal data index). When a user asks a question, the Passage Extractor queries the document store and attempts to extract short sentences or paragraphs that contain relevant answers. You can use a Passage Extractor to answer general questions that you do not have a fact store for, or that do not have a simple answer, such as:
- What is the tallest building in the world?
- What did the only repealed amendment to the US Constitution deal with?
- What is the weight of the Eiffel Tower?
RAG. The RAG (Retrieval Augmented Generation) module uses large language models (LLMs) to generate answers from documents in your system. When a user asks a question, the RAG module queries the document store and finds likely candidates for answers. It provides the original question and relevant content from these candidate documents in a prompt to an external LLM, which generates the answer.

The RAG module provides another approach to answering the same kind of general questions that you might answer with a Passage Extractor system.
Conversation. The Conversation module runs a real time conversation task with your end users. It allows you to set up an interactive virtual assistant to answer common user queries.

You can configure as many different versions of each system as you need. When you send a question to Answer Server, you can specify which of the configured systems you want to retrieve answers from.

The following sections describe the setup for these systems in more detail.

Answer Server System Architecture

The following diagram shows the different components of the Answer Server system.

Answer Bank

The answer bank system uses a dedicated Agentstore component.

Fact Bank

The fact bank system consists of three pieces:

Fact Store (SQL database or Lua script). The fact store contains the factual information that you want to retrieve. Answer Server uses the parsed question and the associated entity and property codes to search the fact store for relevant facts. Usually the fact store component is a SQL database. Alternatively, you can use a Lua script to retrieve facts from an external fact store.
Question Parser (Named Entity Recognition). The fact bank uses a specialized Named Entity Recognition grammar to parse questions and extract the parts of the question that define the fact that the question requests. For example, for the question "what is the population of the USA", Named Entity Recognition determines that the user wants to find the population property of the USA entity. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Coding files. The coding files map entities, properties, and their synonyms to a unique code. Answer Server uses this code to retrieve data from the fact store. For example, the coding files can store the different ways of referring to the country USA as a single code (United States of America, US, and so on). The code can be easily retrieved to match to associated facts.

Passage Extractor

A standard passage extractor system consists of two components:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
Passage Extractor Agentstore. The passage extractor uses Agentstore for some of the entity extraction operations. For example, you can set up agents that define people and place entities, and the passage extractor uses agent queries to extract those entities from the documents that you use to find answers. Agent matching is often quicker than Named Entity Recognition entity matching for simple entities that consist of fixed text, such as names.

The passage extractor also requires:

Named Entity Recognition grammars. The passage extractor uses the Question Parser Named Entity Recognition grammar, as well as grammars for extracting entities from passages that might contain answers, and for identifying sentences and paragraphs that might form legitimate answers, by using pattern matching. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Passage Extractor LLM

The LLM passage extractor requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module contains model files in a format that Answer Server can use to extract and generate your answers. This option uses third-party LLMs, which Answer Server downloads and uses. Alternatively, you can write a script to generate answers, for example from a different third-party LLM system.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Retrieval Augmented Generation

The RAG system requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module defines a script to use to generate the answers from a prompt, which Answer Server provides. The script can use third-party LLMs to generate answers from the prompt.
Prompt template. A template that Answer Server uses to create the prompt. This prompt template includes placeholder tokens that Answer Server replaces with the original user question, and the contextual data that Answer Server retrieves from your data store. The LLM can then use the question and contextual data to generate an answer.

Conversation

The conversation system does not have any required subcomponents. You configure conversation tasks by using a JSON configuration file, which describes the task, including:

introductory text.
the triggers to use to activate a particular conversation or option.
routing information to describe how to proceed through the conversation task, depending on user input.
details of lua scripts to run at particular points in the conversation to parse user input or provide more detailed conversation processing.

You can set your conversation triggers by using fixed phrases, regular expressions, or agents. If you want to use agents as triggers, you must configure an Agentstore component.

Introduction

OpenText Answer Server uses Knowledge Discovery technology to provide specific and concise answers to user questions.

The Answer Server has four types of system to answer different question types.

Answer Bank. The Answer Bank contains a store of reference questions and answers, which you can add and administer. When a user asks a question, the Answer Bank queries the store of existing questions for any that match, and returns the relevant answers. You can use an Answer Bank to maintain an FAQ list to answer questions such as:
- How do I fix my phone screen?
- What does error 404 mean?
- Can I use my phone to send photos of cats?
Fact Bank. The Fact Bank contains a store of factual information, to return simple factual answers. For example, you could use a Fact Bank to answer questions such as:
- What is the population of the USA?
- Who is the CEO of OpenText?
- What is the average June temperature in Antarctica?
Passage Extractor. The Passage Extractor links to a store of documents that contain general information that might be useful for answering questions (for example, your normal data index). When a user asks a question, the Passage Extractor queries the document store and attempts to extract short sentences or paragraphs that contain relevant answers. You can use a Passage Extractor to answer general questions that you do not have a fact store for, or that do not have a simple answer, such as:
- What is the tallest building in the world?
- What did the only repealed amendment to the US Constitution deal with?
- What is the weight of the Eiffel Tower?
RAG. The RAG (Retrieval Augmented Generation) module uses large language models (LLMs) to generate answers from documents in your system. When a user asks a question, the RAG module queries the document store and finds likely candidates for answers. It provides the original question and relevant content from these candidate documents in a prompt to an external LLM, which generates the answer.

The RAG module provides another approach to answering the same kind of general questions that you might answer with a Passage Extractor system.
Conversation. The Conversation module runs a real time conversation task with your end users. It allows you to set up an interactive virtual assistant to answer common user queries.

You can configure as many different versions of each system as you need. When you send a question to Answer Server, you can specify which of the configured systems you want to retrieve answers from.

The following sections describe the setup for these systems in more detail.

Answer Server System Architecture

The following diagram shows the different components of the Answer Server system.

Answer Bank

The answer bank system uses a dedicated Agentstore component.

Fact Bank

The fact bank system consists of three pieces:

Fact Store (SQL database or Lua script). The fact store contains the factual information that you want to retrieve. Answer Server uses the parsed question and the associated entity and property codes to search the fact store for relevant facts. Usually the fact store component is a SQL database. Alternatively, you can use a Lua script to retrieve facts from an external fact store.
Question Parser (Named Entity Recognition). The fact bank uses a specialized Named Entity Recognition grammar to parse questions and extract the parts of the question that define the fact that the question requests. For example, for the question "what is the population of the USA", Named Entity Recognition determines that the user wants to find the population property of the USA entity. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Coding files. The coding files map entities, properties, and their synonyms to a unique code. Answer Server uses this code to retrieve data from the fact store. For example, the coding files can store the different ways of referring to the country USA as a single code (United States of America, US, and so on). The code can be easily retrieved to match to associated facts.

Passage Extractor

A standard passage extractor system consists of two components:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
Passage Extractor Agentstore. The passage extractor uses Agentstore for some of the entity extraction operations. For example, you can set up agents that define people and place entities, and the passage extractor uses agent queries to extract those entities from the documents that you use to find answers. Agent matching is often quicker than Named Entity Recognition entity matching for simple entities that consist of fixed text, such as names.

The passage extractor also requires:

Named Entity Recognition grammars. The passage extractor uses the Question Parser Named Entity Recognition grammar, as well as grammars for extracting entities from passages that might contain answers, and for identifying sentences and paragraphs that might form legitimate answers, by using pattern matching. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Passage Extractor LLM

The LLM passage extractor requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module contains model files in a format that Answer Server can use to extract and generate your answers. This option uses third-party LLMs, which Answer Server downloads and uses. Alternatively, you can write a script to generate answers, for example from a different third-party LLM system.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Retrieval Augmented Generation

The RAG system requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module defines a script to use to generate the answers from a prompt, which Answer Server provides. The script can use third-party LLMs to generate answers from the prompt.
Prompt template. A template that Answer Server uses to create the prompt. This prompt template includes placeholder tokens that Answer Server replaces with the original user question, and the contextual data that Answer Server retrieves from your data store. The LLM can then use the question and contextual data to generate an answer.

Conversation

The conversation system does not have any required subcomponents. You configure conversation tasks by using a JSON configuration file, which describes the task, including:

introductory text.
the triggers to use to activate a particular conversation or option.
routing information to describe how to proceed through the conversation task, depending on user input.
details of lua scripts to run at particular points in the conversation to parse user input or provide more detailed conversation processing.

You can set your conversation triggers by using fixed phrases, regular expressions, or agents. If you want to use agents as triggers, you must configure an Agentstore component.

Introduction

OpenText Answer Server uses Knowledge Discovery technology to provide specific and concise answers to user questions.

The Answer Server has four types of system to answer different question types.

Answer Bank. The Answer Bank contains a store of reference questions and answers, which you can add and administer. When a user asks a question, the Answer Bank queries the store of existing questions for any that match, and returns the relevant answers. You can use an Answer Bank to maintain an FAQ list to answer questions such as:
- How do I fix my phone screen?
- What does error 404 mean?
- Can I use my phone to send photos of cats?
Fact Bank. The Fact Bank contains a store of factual information, to return simple factual answers. For example, you could use a Fact Bank to answer questions such as:
- What is the population of the USA?
- Who is the CEO of OpenText?
- What is the average June temperature in Antarctica?
Passage Extractor. The Passage Extractor links to a store of documents that contain general information that might be useful for answering questions (for example, your normal data index). When a user asks a question, the Passage Extractor queries the document store and attempts to extract short sentences or paragraphs that contain relevant answers. You can use a Passage Extractor to answer general questions that you do not have a fact store for, or that do not have a simple answer, such as:
- What is the tallest building in the world?
- What did the only repealed amendment to the US Constitution deal with?
- What is the weight of the Eiffel Tower?
RAG. The RAG (Retrieval Augmented Generation) module uses large language models (LLMs) to generate answers from documents in your system. When a user asks a question, the RAG module queries the document store and finds likely candidates for answers. It provides the original question and relevant content from these candidate documents in a prompt to an external LLM, which generates the answer.

The RAG module provides another approach to answering the same kind of general questions that you might answer with a Passage Extractor system.
Conversation. The Conversation module runs a real time conversation task with your end users. It allows you to set up an interactive virtual assistant to answer common user queries.

You can configure as many different versions of each system as you need. When you send a question to Answer Server, you can specify which of the configured systems you want to retrieve answers from.

The following sections describe the setup for these systems in more detail.

Answer Server System Architecture

The following diagram shows the different components of the Answer Server system.

Answer Bank

The answer bank system uses a dedicated Agentstore component.

Fact Bank

The fact bank system consists of three pieces:

Fact Store (SQL database or Lua script). The fact store contains the factual information that you want to retrieve. Answer Server uses the parsed question and the associated entity and property codes to search the fact store for relevant facts. Usually the fact store component is a SQL database. Alternatively, you can use a Lua script to retrieve facts from an external fact store.
Question Parser (Named Entity Recognition). The fact bank uses a specialized Named Entity Recognition grammar to parse questions and extract the parts of the question that define the fact that the question requests. For example, for the question "what is the population of the USA", Named Entity Recognition determines that the user wants to find the population property of the USA entity. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Coding files. The coding files map entities, properties, and their synonyms to a unique code. Answer Server uses this code to retrieve data from the fact store. For example, the coding files can store the different ways of referring to the country USA as a single code (United States of America, US, and so on). The code can be easily retrieved to match to associated facts.

Passage Extractor

A standard passage extractor system consists of two components:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
Passage Extractor Agentstore. The passage extractor uses Agentstore for some of the entity extraction operations. For example, you can set up agents that define people and place entities, and the passage extractor uses agent queries to extract those entities from the documents that you use to find answers. Agent matching is often quicker than Named Entity Recognition entity matching for simple entities that consist of fixed text, such as names.

The passage extractor also requires:

Named Entity Recognition grammars. The passage extractor uses the Question Parser Named Entity Recognition grammar, as well as grammars for extracting entities from passages that might contain answers, and for identifying sentences and paragraphs that might form legitimate answers, by using pattern matching. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Passage Extractor LLM

The LLM passage extractor requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module contains model files in a format that Answer Server can use to extract and generate your answers. This option uses third-party LLMs, which Answer Server downloads and uses. Alternatively, you can write a script to generate answers, for example from a different third-party LLM system.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Retrieval Augmented Generation

The RAG system requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module defines a script to use to generate the answers from a prompt, which Answer Server provides. The script can use third-party LLMs to generate answers from the prompt.
Prompt template. A template that Answer Server uses to create the prompt. This prompt template includes placeholder tokens that Answer Server replaces with the original user question, and the contextual data that Answer Server retrieves from your data store. The LLM can then use the question and contextual data to generate an answer.

Conversation

The conversation system does not have any required subcomponents. You configure conversation tasks by using a JSON configuration file, which describes the task, including:

introductory text.
the triggers to use to activate a particular conversation or option.
routing information to describe how to proceed through the conversation task, depending on user input.
details of lua scripts to run at particular points in the conversation to parse user input or provide more detailed conversation processing.

You can set your conversation triggers by using fixed phrases, regular expressions, or agents. If you want to use agents as triggers, you must configure an Agentstore component.

Introduction

OpenText Answer Server uses Knowledge Discovery technology to provide specific and concise answers to user questions.

The Answer Server has four types of system to answer different question types.

Answer Bank. The Answer Bank contains a store of reference questions and answers, which you can add and administer. When a user asks a question, the Answer Bank queries the store of existing questions for any that match, and returns the relevant answers. You can use an Answer Bank to maintain an FAQ list to answer questions such as:
- How do I fix my phone screen?
- What does error 404 mean?
- Can I use my phone to send photos of cats?
Fact Bank. The Fact Bank contains a store of factual information, to return simple factual answers. For example, you could use a Fact Bank to answer questions such as:
- What is the population of the USA?
- Who is the CEO of OpenText?
- What is the average June temperature in Antarctica?
Passage Extractor. The Passage Extractor links to a store of documents that contain general information that might be useful for answering questions (for example, your normal data index). When a user asks a question, the Passage Extractor queries the document store and attempts to extract short sentences or paragraphs that contain relevant answers. You can use a Passage Extractor to answer general questions that you do not have a fact store for, or that do not have a simple answer, such as:
- What is the tallest building in the world?
- What did the only repealed amendment to the US Constitution deal with?
- What is the weight of the Eiffel Tower?
RAG. The RAG (Retrieval Augmented Generation) module uses large language models (LLMs) to generate answers from documents in your system. When a user asks a question, the RAG module queries the document store and finds likely candidates for answers. It provides the original question and relevant content from these candidate documents in a prompt to an external LLM, which generates the answer.

The RAG module provides another approach to answering the same kind of general questions that you might answer with a Passage Extractor system.
Conversation. The Conversation module runs a real time conversation task with your end users. It allows you to set up an interactive virtual assistant to answer common user queries.

You can configure as many different versions of each system as you need. When you send a question to Answer Server, you can specify which of the configured systems you want to retrieve answers from.

The following sections describe the setup for these systems in more detail.

Answer Server System Architecture

The following diagram shows the different components of the Answer Server system.

Answer Bank

The answer bank system uses a dedicated Agentstore component.

Fact Bank

The fact bank system consists of three pieces:

Fact Store (SQL database or Lua script). The fact store contains the factual information that you want to retrieve. Answer Server uses the parsed question and the associated entity and property codes to search the fact store for relevant facts. Usually the fact store component is a SQL database. Alternatively, you can use a Lua script to retrieve facts from an external fact store.
Question Parser (Named Entity Recognition). The fact bank uses a specialized Named Entity Recognition grammar to parse questions and extract the parts of the question that define the fact that the question requests. For example, for the question "what is the population of the USA", Named Entity Recognition determines that the user wants to find the population property of the USA entity. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Coding files. The coding files map entities, properties, and their synonyms to a unique code. Answer Server uses this code to retrieve data from the fact store. For example, the coding files can store the different ways of referring to the country USA as a single code (United States of America, US, and so on). The code can be easily retrieved to match to associated facts.

Passage Extractor

A standard passage extractor system consists of two components:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
Passage Extractor Agentstore. The passage extractor uses Agentstore for some of the entity extraction operations. For example, you can set up agents that define people and place entities, and the passage extractor uses agent queries to extract those entities from the documents that you use to find answers. Agent matching is often quicker than Named Entity Recognition entity matching for simple entities that consist of fixed text, such as names.

The passage extractor also requires:

Named Entity Recognition grammars. The passage extractor uses the Question Parser Named Entity Recognition grammar, as well as grammars for extracting entities from passages that might contain answers, and for identifying sentences and paragraphs that might form legitimate answers, by using pattern matching. The Named Entity Recognition module is embedded in Answer Server, so you do not need to install a separate component.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Passage Extractor LLM

The LLM passage extractor requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module contains model files in a format that Answer Server can use to extract and generate your answers. This option uses third-party LLMs, which Answer Server downloads and uses. Alternatively, you can write a script to generate answers, for example from a different third-party LLM system.
Classifier training files. These files define types of questions, which determine the type of answer it looks for. You can configure Answer Server to save the training files and training data.

Retrieval Augmented Generation

The RAG system requires:

Data Store (Content component). The data store is a Content component that contains the documents that you want to attempt to extract answers from. This might be a general knowledge base (such as an index of Wikipedia documents), or a data set that is more specific to your business use (such as an index of your company policy documents). This data store does not have to be unique to Answer Server. That is, you can use your normal data Content component.
LLM Module. The LLM module defines a script to use to generate the answers from a prompt, which Answer Server provides. The script can use third-party LLMs to generate answers from the prompt.
Prompt template. A template that Answer Server uses to create the prompt. This prompt template includes placeholder tokens that Answer Server replaces with the original user question, and the contextual data that Answer Server retrieves from your data store. The LLM can then use the question and contextual data to generate an answer.

Conversation

The conversation system does not have any required subcomponents. You configure conversation tasks by using a JSON configuration file, which describes the task, including:

introductory text.
the triggers to use to activate a particular conversation or option.
routing information to describe how to proceed through the conversation task, depending on user input.
details of lua scripts to run at particular points in the conversation to parse user input or provide more detailed conversation processing.

You can set your conversation triggers by using fixed phrases, regular expressions, or agents. If you want to use agents as triggers, you must configure an Agentstore component.

Install and Set Up Answer Server

This section describes how to install Answer Server.

Install Answer Server

Answer Server is available as a ZIP package which includes the files you need to set up Answer Server.

The Answer Server ZIP package includes:

the Answer Server executable file.
the Answer Server configuration file.

It also includes the appropriate data and configuration files for the different answer systems.

For Answer Bank, the ZIP package includes:

a configuration file for the Answer Bank Agentstore component

For Fact Bank, the ZIP package includes:

the Fact Bank Named Entity Recognition grammar ECR and XML files
the Fact Bank Named Entity Recognition Lua scripts
a set of example files for setting up a SQL fact store
a simple example script for creating a Lua fact store

For Passage Extractor, the ZIP package includes:

a configuration file for the Passage Extractor Agentstore component
sample entity IDX files for the Passage Extractor Agentstore entity extraction
the classifier and label files for the passage extractor question classifiers
the entity_extraction.json and surface_patterns.json configuration files
the Passage Extractor Named Entity Recognition grammar, and several entity extraction Named Entity Recognition grammar ECR files

To install Answer Server, download and unzip the package. You can optionally install Answer Server as a service. See Install a Component as a Service on Windows or Install a Component as a Service on Linux.

The ZIP package does not include the subcomponent executable files. For each system, you must also download and install the associated subcomponents. The following sections provide more information about the requirements for each system:

Set Up an Answer Bank System
Set Up a Fact Bank System
Set Up a Passage Extractor System

External Dependencies

On Linux operating system platforms, if you want to use any of the functionality that uses an ODBC connection, OpenText recommends explicitly setting the ODBCSYSINI environment variable. This variable specifies the directory that contains the odbcinst.ini file, which contains details of available ODBC drivers on your system.

For example, on some systems you must set ODBCSYSINI=/etc, and on others ODBCSYSINI=/usr/local/etc.

In particular, OpenText recommends that you set this environment variable if you want to use a SQL Fact Store with your Fact Bank systems, or Answer Bank statistics.

Install a Component as a Service on Windows

On Microsoft Windows operating systems, you can install any Knowledge Discovery component as a Windows service. Installing a component as a Windows service makes it easy to start and stop the component, and you can configure a component to start automatically when you start Windows.

Use the following procedure to install Answer Server as a Windows service from a command line.

To install a component as a Windows service

Open a command prompt with administrative privileges (right-click the icon and select Run as administrator).
Navigate to the directory that contains the component that you want to install as a service.

Send the following command:

Component.exe -install

where Component.exe is the executable file of the component that you want to install as a service.

The -install command has the following optional arguments:


`-start {[auto]	[manual]
`-username UserName`	The user name that the service runs under. By default, it uses a local system account.
`-password Password`	The password for the service user.
`-servicename ServiceName`	The name to use for the service. If your service name contains spaces, use quotation marks (") around the name. By default, it uses the executable name.
`-displayname DisplayName`	The name to display for the service in the Windows services manager. If your display name contains spaces, use quotation marks (") around the name. By default, it uses the service name.
`-depend Dependency1[,Dependency2 ...]`	A comma-separated list of the names of Windows services that Windows must start before the new service. For example, you might want to add the License Server as a dependency.

For example:

Component.exe -install -servicename ServiceName -displayname "Component Display Name" -depend LicenseServer

After you have installed the service, you can start and stop the service from the Windows Services manager.

When you no longer require a service, you can uninstall it again.

To uninstall a Windows Service

Open a command prompt.
Navigate to the directory that contains the component service that you want to uninstall.
Send the following command:
```
Component.exe -uninstall
```
where Component.exe is the executable file of the component service that you want to uninstall.

If you did not use the default service name when you installed the component, you must also add the -servicename argument. For example:
```
Component.exe -uninstall -servicename ServiceName
```

Install a Component as a Service on Linux

On Linux operating systems, you can install a component as a service to allow you to easily start and stop it. You can also configure the service to run when the machine boots. The following procedures describe how to install Answer Server as a service on Linux.

NOTE: To use these procedures, you must have root permissions.

The procedure that you must use depends on the init system.

For Linux operating systems that use systemd, see systemd.
For Linux operating systems that use System V, see System V.

systemd

NOTE: If your setup has an externally mounted drive that Answer Server uses, you might need to modify the init script. The installed init script contains examples for an NFS mount requirement.

To install a component as a service

Navigate to the init/systemd directory, in the component installation folder.
Open the service configuration file and fill in the placeholder values. For more information about these placeholders, refer to the file readme.md in the init directory.
Run the appropriate command to copy the service configuration file to the appropriate directory.
- Red Hat Enterprise Linux (and CentOS)
```
cp InstallDir/init/systemd/componentname.service /etc/systemd/system/componentname.service
```
- Debian (including Ubuntu):
```
cp InstallDir/init/systemd/componentname.service /lib/systemd/system/componentname.service
```
where componentname is the name of the service configuration file that you want to use, which is the name of the component executable (without the file extension).

For other Linux environments, refer to the operating system documentation.
Run the following commands to set the appropriate access, owner, and group permissions for the component:
- Red Hat Enterprise Linux (and CentOS)
```
chmod 755 /etc/systemd/system/componentname.service
chown root /etc/systemd/system/componentname.service
chgrp root /etc/systemd/system/componentname.service
```
- Debian (including Ubuntu):
```
chmod 755 /lib/systemd/system/componentname.service
chown root /lib/systemd/system/componentname.service
chgrp root /lib/systemd/system/componentname.service
```
where componentname is the name of the component executable that you want to run (without the file extension).

For other Linux environments, refer to the operating system documentation.
(Optional) If you want to start the component when the machine boots, run the following command:
```
systemctl enable componentname
```

TIP: On systemd systems, services do not inherit file handle limits from the system limits or user settings. The default limits for services are configured separately in /*/systemd/system.conf and /*/systemd/user.conf.

In some cases this behavior might mean that a component fails to operate because it runs out of file handles. In this case, you can modify the LimitNOFILE parameter in the componentname.service file to increase the file handle limit before you install the service. Alternatively, you can create an override.conf file for the service.

System V

To install a component as a service

Navigate to the init/systemv directory, in the component installation folder.
Open the init script and fill in the placeholder values. For more information about these placeholders, refer to the file readme.md in the init directory.
Run the following command to copy the init scripts to your init.d directory.
```
cp InstallDir/init/systemv/componentname /etc/init.d/
```
where componentname is the name of the init script that you want to use, which is the name of the component executable (without the file extension).

Run the following commands to set the appropriate access, owner, and group permissions for the component:

chmod 755 /etc/init.d/componentname
chown root /etc/init.d/componentname
chgrp root /etc/init.d/componentname

(Optional) If you want to start the component when the machine boots, run the appropriate command for your Linux operating system environment:
- Red Hat Enterprise Linux (and CentOS):
```
chkconfig --add componentname  
chkconfig componentname on
```
- Debian (including Ubuntu):
```
update-rc.d componentname defaults
```
For other Linux environments, refer to the operating system documentation.

Configure Answer Server

The following sections describe how to configure Answer Server and the subcomponents that you need to use to run your systems.

General Configuration

The [Server] section of the Answer Server configuration file contains general settings that affect the server. In most cases, the only parameter that you might need to modify is the Port parameter, which controls the port that Answer Server listens on. This port must not be used by any other service on the host machine.

For example:

[Server]  
Port=12000

Similarly, the [Service] section controls the behavior on the service port. You must make sure that the ServicePort parameter uses a port that is not used by any other service.

For example:

[Service]  
ServicePort=12002

You must also configure the License Server for your system. For more information, see Configure the License Server Host and Port.

Configure Answer Server Systems

To set up your answer server, you must configure one or more systems to use to retrieve questions. The [Systems] configuration section contains a list of systems that you want to configure. See Systems Configuration Parameters.

The order in which you specify the systems is also the default order in which Answer Server requests answers from the systems. You can override this ordering for an individual action (see Ask Questions in Answer Server).

[Systems]  
0=MyFactBank  
1=MyAnswerBank

For each of these systems, you then create a configuration section with the same name, which contains the settings for that system.

NOTE: System names are case-sensitive.

Configure an Answer Bank System

For an Answer Bank system, you must set Type to answerbank. You must also configure the host and port of the Agentstore component that you are using as the Answer Bank.

[MyAnswerBank]
Type=answerbank
IDOLHost=localhost
IDOLACIPort=6000

For more information, see Set Up an Answer Bank System and Answer Bank System Configuration Parameters.

Configure a Fact Bank System

For a Fact Bank system, you must set Type to factbank. You must also configure the question parser grammars, the fact store, and the location of the coding files.

[MyFactBank]
Type=factbank
// Question Parser
EductionQuestionGrammars=./resources/grammars/question_grammar_en.ecr
EductionLuaScript=./resources/lua/question_grammar_en.lua
EductionTimeGrammars=./resources/grammars/datetime_processing.ecr
TimeLuaScript=./resources/lua/datetime.lua
// Fact Store
BackendType=sqldb
ConnectionString=Driver=PostgreSQL ANSI(x64); Server=sql-host.mycompany.com; Port=5432; Database=factstoredb; Uid=postgres;password=password;
// Coding Files
CodingsPath=./codings
CodingsDatPath=./codings

For more information, see Set Up a Fact Bank System and Fact Bank System Configuration Parameters.

Configure a Passage Extractor System

For a Passage Extractor system, you must set Type to passageextractor. You must also configure the host and port of the Content component data store, as well as the Named Entity Recognition grammars and Agentstore components to use for entity extraction. You can also optionally define the locations of the classifier file and label file to allow you to save your training classifiers.

[MyPassageExtractor]
Type=PassageExtractor
// Data store Content
IdolHost=localhost
IdolAciport=6002
// Entity Agentstore
AgentStoreHost=localhost
AgentStoreAciport=5002
// Named Entity Recognition
EductionGrammars=./resources/grammars/question_grammar_en.ecr,./passageextractor/grammers/number_en.ecr,./passageextractor/grammars/person_en.ecr,./passageextractor/grammars/date_en.ecr,./passageextractor/grammars/money_en.ecr
// Classifier Files
ClassifierFile=./passageextractor/classifiertraining/svm_en.dat
LabelFile=./passageextractor/classifiertraining/labels_en.dat
EntityExtractionFile=./passageextractor/configuration/entity_extraction_en.json
SurfacePatternsFile=./passageextractor/configuration/surface_patterns_en.json
ClassifierBehaviorFile=./passageextractor/configuration/classifier_behavior.json

For more information, see Set Up a Passage Extractor System and Passage Extractor System Configuration Parameters.

Configure a Passage Extractor LLM System

For a Passage Extractor system, you must set Type to passageextractorLLM. You must also configure the host and port of the Content component data store, as well as the details of your LLM module. You can also optionally define the locations of the classifier file and label file to allow you to save your training classifiers.

[MyPassageExtractorLLM]
Type=PassageExtractorLLM
// Data store Content
IdolHost=localhost
IdolAciport=6002
// Classifier Files
ClassifierFile=./passageextractor/classifiertraining/svm_en.dat
LabelFile=./passageextractor/classifiertraining/labels_en.dat
// Module to use
ModuleID=LLMExtractiveQuestionAnswering-Small

[LLMExtractiveQuestionAnswering-Small]
Type=ExtractiveQuestionAnsweringLLM
ModelPath=LLMFiles/model.pt
TokenizerPath=LLMFiles/tokenizer.spiece.model

For more information, see Set Up a Passage Extractor LLM System and Passage Extractor LLM System Configuration Parameters.

Configure a Conversation System

For a Conversation system, you must set Type to conversation. You must also configure the location of a task configuration file, which defines the conversation task in more detail. You can also optionally define the location of an Agentstore component to use to store conversation trigger agents, and session expiration for the conversation sessions.

[MyConversation]
Type=Conversation
TaskConfigurationFile=C:\AnswerServer\Conversation\tasks.json
// Trigger Agentstore
AgentStoreHost=localhost
AgentStoreAciport=5002
// Session Expiration
SessionExpirationIdleTime=600
SessionExpirationInterval=60

For more information, see Set Up a Conversation System and Conversation System Configuration Parameters.

Configure a Remote System

For a Remote system, you must set Type to Remote. You must also configure the location of the remote Answer Server, and the name of the system that is configured in the remote Answer Server. You can also optionally configure default values for Ask action parameters.

[MyRemoteSystem]
Type=Remote
AnswerSystem=AnswerBank
AnswerServerACIPort=7000
AnswerServerHost=server1.example.com

For more information, see Set Up a Remote Answer System and Remote System Configuration Parameters.

Language Configuration

The Answer Server functionality uses language-dependent information to parse and classify questions and match them to answers.

Answer Bank Language Configuration

In the answer bank systems, the language-dependent processing is managed by the answer bank Agentstore component. The Agentstore component stores the questions, answers, and processes the Ask actions as queries.

You can configure languages in the Agentstore in the same way as in the Content component. For more information, refer to the Content Component Help and the Knowledge Discovery Administration Guide.

Fact Bank and Passage Extractor Language Configuration

In fact bank and passage extractor systems, Answer Server can use stemming and stop lists to improve the question parsing and answer matching.

Stemming is the process of reducing related words, such as plurals and verb forms, to a common linguistic root. For example, in English, helping, helped, and helps all derive from the common root help.

Stemming rules are language-dependent. To get the best possible results, you must specify the language that you use in your questions.
A stop list is a list of very common words, which usually add very little meaning to phrases. For example, in English, the and and can often be ignored without losing the sense of a sentence. Knowledge Discovery uses stop lists to optimize matching.

In a fact bank system, Answer Server uses the stop list to match fact bank codes more broadly. Answer Server attempts to form pseudonym values in the code maps by taking the existing code phrases and removing stop words from the beginning and end of the phrase. Similarly, when Answer Server attempts to match a string to codes, it matches the full phrase, and the phrase with the stop words removed from the beginning and end of the phrase. Answer Server does not attempt to remove stop words from the middle of phrases.

In a passage extractor system, Answer Server removes stop words from the classified questions to attempt to find the best match in the data Content component. Answer Server does not use the stop list for question classification, which often depends on common words, such as question words.

By default, Answer Server uses English stemming rules, and does not use a stop list. If you use the default fact bank and passage extractor grammar files, this is usually appropriate, although you might want to add an English stop list, by setting the StopList configuration parameter.

To use fact bank and passage extractor with different languages, you need a version of the grammar files in the appropriate language. These grammar files are available in English, French, German, Italian, Portuguese, and Spanish. If you are interested in using fact bank and passage extractor in other languages, contact your OpenText account manager.

If you are using fact bank and passage extractor in a language other than English, you can change the stemming language by modifying the Language configuration parameter. You can also add a stop list by setting the StopList configuration parameter.

You can configure the location where you store your language files (such as stop lists), by using the LanguageDirectory configuration parameter.

You can define language configuration in the [Server] section, to apply to all your systems. You can also set the language configuration parameters in your individual system configuration sections. If you set the parameters in both sections, the system configuration takes precedence.

For more information about these parameters, refer to the Answer Server Reference.

Use Synonyms to Expand Queries

Answer Server can communicate with a Query Manipulation Server (QMS) and use synonyms to expand queries. This increases the likelihood that Answer Server can find an answer to a question. You can manage your synonyms through Data Admin.

Synonyms can be used with all Answer Server systems.

To configure a synonym store

Open the Answer Server configuration file.
In the [Server] section, set the parameter SynonymStore. This specifies the name of another section in the configuration file that contains information about the synonym store.
Add a new section to the configuration file, using the name you specified in the previous step. In the new section, set the following parameters:

Host The host name or IP address of the QMS that provides access to your synonym rules.

ACIPort The ACI port of the QMS that provides access to your synonym rules.

For example:
```
[Server]
SynonymStore=SynonymQMS

[SynonymQMS]
Host=localhost
ACIPort=16000
```
Save and close the configuration file.


Host	The host name or IP address of the QMS that provides access to your synonym rules.
ACIPort	The ACI port of the QMS that provides access to your synonym rules.

NOTE: When you configure a Passage Extractor system, you normally set the IDOLHost and IDOLACIPort parameters to the host and port of the Content component that contains your documents. To enable synonyms, you must set these parameters to the host and port of the QMS that provides access to your synonyms. Set the host and port of the Content component in the QMS configuration file instead. For more information about configuring a passage extractor system, see Configure the Passage Extractor System.

Update Synonyms

After you add, modify, or delete synonyms, Answer Server must update answer bank rules and other relevant data. If you change your synonyms through the Data Admin interface, the application sends information about the changes to Answer Server. However, you might interact with the Agentstore directly. For example, you might restore a backup of your synonym data. In this case you can instruct Answer Server that there have been changes in the synonym store by sending a ManageResources action. For example:

action=ManageResources
data={
   "operation":"refresh",
   "type":"synonym"
}

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

Configure Client Authorization

You can configure Answer Server to authorize different operations for different connections.

Authorization roles define a set of operations for a set of users. You define the operations by using the StandardRoles configuration parameter, or by explicitly defining a list of allowed actions in the Actions and ServiceActions parameters. You define the authorized users by using a client IP address, SSL identities, and GSS principals, depending on your security and system configuration.

For more information about the available parameters, see the Answer Server Reference.

IMPORTANT: To ensure that Answer Server allows only the options that you configure in [AuthorizationRoles], make sure that you delete any deprecated RoleClients parameters from your configuration (where Role corresponds to a standard role name, for example AdminClients).

To configure authorization roles

Open your configuration file in a text editor.
Find the [AuthorizationRoles] section, or create one if it does not exist.
In the [AuthorizationRoles] section, list the user authorization roles that you want to create. For example:
```
[AuthorizationRoles]
0=AdminRole
1=UserRole
```
Create a section for each authorization role that you listed. The section name must match the name that you set in the [AuthorizationRoles] list. For example:
```
[AdminRole]
```
In the section for each role, define the operations that you want the role to be able to perform. You can set StandardRoles to a list of appropriate values, or specify an explicit list of allowed actions by using Actions, and ServiceActions. For example:
```
[AdminRole]
StandardRoles=Admin,ServiceControl,ServiceStatus

[UserRole]
Actions=GetVersion
ServiceActions=GetStatus
```
NOTE: The standard roles do not overlap. If you want a particular role to be able to perform all actions, you must include all the standard roles, or ensure that the clients, SSL identities, and so on, are assigned to all relevant roles.
In the section for each role, define the access permissions for the role, by setting Clients, SSLIdentities, and GSSPrincipals, as appropriate. If an incoming connection matches one of the allowed clients, principals, or SSL identities, the user has permission to perform the operations allowed by the role. For example:
```
[AdminRole]
StandardRoles=Admin,ServiceControl,ServiceStatus
Clients=localhost
SSLIdentities=admin.example.com
```
Save and close the configuration file.
Restart Answer Server for your changes to take effect.

IMPORTANT: If you do not provide any authorization roles for a standard role, Answer Server uses the default client authorization for the role (localhost for Admin and ServiceControl, all clients for Query and ServiceStatus). If you define authorization only by actions, OpenText recommends that you configure an authorization role that disallows all users for all roles by default. For example:

[ForbidAllRoles]  
StandardRoles=*  
Clients=""

This configuration ensures that Answer Server uses only your action-based authorizations.

Configure SSL Communication Between Components

You can configure Answer Server to use SSL to connect to each of its back end components, such as the Content and Agentstore components that you use in your systems.

For each child component, there is a ComponentHost and an ComponentACIPort configuration parameter in the system configuration, which specifies how to connect to the component. You can also add the ComponentSSLConfig parameter. For example, for the Content component, you use IDOLHost, IDOLACIPort, IDOLSSLConfig.

You set the ComponentSSLConfig parameter to the name of the configuration section where you define the SSL settings for connection to that component. By convention, this section has the name SSLOptionN.

NOTE: For the Agentstore and Content component, Answer Server uses the same SSL configuration for ACI and indexing requests.

For example:

[MyPassageExtractor]
Type=passageextractor
// Data Content
IDOLHost=localhost
IDOLACIPort=10050
IDOLSSLConfig=SSLOption1
// Entity Agentstore
AgentstoreHost=localhost
AgentstoreACIPort=10060
IDOLSSLConfig=SSLOption0
...

[SSLOption0]
SSLMethod=TLSV1.3
SSLCertificate=host1.crt
SSLPrivateKey=host1.key
SSLCACertificate=trusted.crt

[SSLOptions1] 
SSLMethod=TLSV1.3
SSLCertificate=host2.crt
SSLPrivateKey=9s7BxMjD2d3M3t7awt/J8A
SSLCACertificate=trusted.crt

For more information about the SSL configuration options, see Secure Socket Layer Parameters.

Customize Logging

You can customize logging by setting up your own log streams. Each log stream creates a separate log file in which specific log message types (for example, action, index, application, or import) are logged.

To set up log streams

Open your configuration file in a text editor.
Find the [Logging] section. If the configuration file does not contain a [Logging] section, add one.
In the [Logging] section, create a list of the log streams that you want to set up, in the format N=LogStreamName. List the log streams in consecutive order, starting from 0 (zero). For example:
```
[Logging]
LogLevel=FULL
LogDirectory=logs
0=ApplicationLogStream
1=ActionLogStream
```
You can also use the [Logging] section to configure any default values for logging configuration parameters, such as LogLevel. For more information, see the Answer Server Reference.
Create a new section for each of the log streams. Each section must have the same name as the log stream. For example:
```
[ApplicationLogStream]
[ActionLogStream]
```

Specify the settings for each log stream in the appropriate section. You can specify the type of logging to perform (for example, full logging), whether to display log messages on the console, the maximum size of log files, and so on. For example:

[ApplicationLogStream]
LogTypeCSVs=application
LogFile=application.log
LogHistorySize=50
LogTime=True
LogEcho=False
LogMaxSizeKBs=1024

[ActionLogStream]
LogTypeCSVs=action
LogFile=logs/action.log
LogHistorySize=50
LogTime=True
LogEcho=False
LogMaxSizeKBs=1024

Save and close the configuration file. Restart the service for your changes to take effect.

Validate the Configuration File

You can use the ValidateConfig service action to check for errors in the configuration file.

NOTE: For the ValidateConfig action to validate a configuration section, Answer Server must have previously read that configuration. In some cases, the configuration might be read when a task is run, rather than when the component starts up. In these cases, ValidateConfig reports any unread sections of the configuration file as unused.

To validate the configuration file

Send the following action to Answer Server:
```
http://Host:ServicePort/action=ValidateConfig
```
where:

Host is the host name or IP address of the machine where Answer Server is installed.

ServicePort is the service port, as specified in the [Service] section of the configuration file.


`Host`	is the host name or IP address of the machine where Answer Server is installed.
`ServicePort`	is the service port, as specified in the `[Service]` section of the configuration file.

Run Answer Server

This section describes how to start and stop Answer Server, and to send actions.

Start Answer Server

NOTE: Your License Server must be running before you start Answer Server.

TIP: You can configure services to start automatically when you start the machine.

To start Answer Server

Start Answer Server from the command line using the following command:
```
answerserver.exe -configfile configname.cfg
```
where the optional -configfile argument specifies the path of a configuration file to use.
On Windows, if you have installed Answer Server as a service, start the service from the Windows Services dialog box.
On Linux, if you have installed Answer Server as a service, use one of the following commands:
- On machines that use systemd:
  
  systemctl start answerserver
- On machines that use system V:
  
  service answerserver start
On Linux you can use the script start-answerserver.sh which is provided in the installation directory.

Stop Answer Server

You can stop Answer Server by using one of the following procedures.

To stop Answer Server

Send the Stop service action to the service port.

http://host:ServicePort/action=Stop

where:


`host`	is the host name or IP address of the machine where Answer Server is installed.
`ServicePort`	is the Answer Server service port (specified in the `[Service]` section of the configuration file).

On Windows, if Answer Server is running as a service, stop Answer Server from the Windows Services dialog box.
On Linux, if Answer Server is running as a service, use one of the following commands:
- On machines that use systemd:
  
  systemctl stop answerserver
- On machines that use system V:
  
  service answerserver stop
On Linux, if you started Answer Server with the script start-answerserver.sh, run the script stop-answerserver.sh which is provided in the installation directory.

Send Actions to Answer Server

Answer Server actions are HTTP requests, which you can send, for example, from your web browser. The general syntax of these actions is:

http://host:port/action=action&parameters

where:


`host`	is the IP address or name of the machine where Answer Server is installed.
`port`	is the Answer Server ACI port. The ACI port is specified by the `Port` parameter in the `[Server]` section of the Answer Server configuration file. For more information about the `Port` parameter, see the Answer Server Reference.
`action`	is the name of the action you want to run.
`parameters`	are the required and optional parameters for the action.

NOTE: Separate individual parameters with an ampersand (&). Separate parameter names from values with an equals sign (=). You must percent-encode all parameter values.

For more information about actions, see the Answer Server Reference.

Configure Answer Server Systems

This section describes how to configure and use the different types of systems in Answer Server.

Set Up an Answer Bank System
Set Up a Fact Bank System
Set Up a Passage Extractor System
Set Up a Remote Answer System
Ask Questions in Answer Server
Set Up a Conversation System
Hold Conversations in Answer Server

Set Up an Answer Bank System

This section describes how to set up an Answer Bank system, and add questions, question equivalence classes, and answers.

Configure the Answer Bank System

The Answer Server configuration file contains information about the subcomponents in your Answer Bank systems.

For any Answer Bank system, you must configure the host and port details of the Answer Bank Agentstore, which is a specially configured Content component that stores your questions, answers, and question equivalence classes.

The following procedure describes how to configure the Answer Bank system in Answer Server.

There are also several optional parameters in the Answer Bank system, to allow you to modify the paths that Answer Bank uses for failed and queued actions, and how often it updates the Answer Bank usage statistics.

For more details about the configuration parameters for the Answer Bank system, refer to the Answer Server Reference.

To configure the Answer Bank System

Open the Answer Server configuration file in a text editor.
Find the [Systems] section, or create one if it does not exist. This section contains a list of systems, which refer to the associated configuration sections for each system.
After any existing systems, add an entry for your new Answer Bank system. For example:
```
[Systems]
0=MyFactBank
1=MyAnswerBank
```
Create a configuration section for your Answer Bank system, with the name that you specified. For example, [MyAnswerBank].
Set Type to AnswerBank. Set IDOLHost and IDOLACIPort to the host name and ACI Port of the Agentstore component that contains the questions and answers. For example:
```
[MyAnswerBank]
Type=answerbank
IDOLHost=localhost
IDOLACIPort=6000
```
Save and close the configuration file.
Restart Answer Server for your changes to take effect.
(Optional) The Answer Server installation includes a default set of interrogative synonyms (such as "what time"/"when" or "where"/"which location") that you can use to help Answer Server answer questions that are posed in different ways. If you want to use the synonyms, first configure your synonym store as described in Use Synonyms to Expand Queries. Then use the DREADD index action to index the synonym rules into your Agentstore component. The synonyms are available in the resources/synonyms folder of the Answer Server installation. OpenText also recommends that you configure your Agentstore to use a stoplist provided in the resources/stoplists folder. Otherwise, many of the synonyms will be considered to be stopwords.

Configure the Answer Bank Agentstore

An Answer Bank system requires an Agentstore component, which is a specialized configuration of the Content component.

The Answer Server package includes a predefined configuration file for the Answer Bank Agentstore component, which includes the relevant field and server configuration for Answer Server. You must download and install the Content component separately, and then update the configuration file with the Answer Bank Agentstore-specific configurations.

To configure the Agentstore component for your Answer Bank

In your Answer Server installation directory, copy the Answer Bank Agentstore configuration file (agentstore.cfg).
Open your Content component installation directory.
Paste the Answer Server Agentstore configuration file. Overwrite the installed configuration file (you might want to make a copy of it first).

NOTE: The configuration file must have the same name as the executable file.
Open the configuration file in a text editor.
Update the [License] section with the host and port information for your License Server. For more information, see Configure the License Server Host and Port.
Find the [Server] section Port parameter. Check that the specified port is available on the host machine, or change it to an available port.
Find the [Service] section ServicePort parameter. Check that the specified port is available on the host machine, or change it to an available port.
Save and close the configuration file.

Manage an Answer Bank

You manage the questions and answers in your Answer Bank by using the ManageResources action. This action allows you to upload a JSON object that contains the changes that you want to make in the Answer Bank.

You can also use the Data Admin user interface to manage the questions and answers in your Answer Bank. For more information, refer to the Data Admin User Guide.

Find the JSON Schema for Your Update

The schemas for the ManageResources action are stored in Answer Server. You can retrieve them by using the GetResources action. You can restrict this action to a particular system in your configuration file by specifying the SystemName parameter.

For example:

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=Schema

NOTE: System names are case sensitive. The value that you specify in the SystemName parameter must match the name of the system in the configuration file.

Add a Question

You can use the add question operation to keep track of questions that your users ask, and to make rules based on real questions that hopefully match future questions. For example, you might have your user interface set up to add every question that does not have an answer to the Answer Bank, to build up a list of frequently asked questions, which you can add answers for.

To add a question, you use a ManageResources action in a POST request method, with the update provided in the Data parameter as a JSON object.

The following simple example adds a question to the AnswerBank system.

Action=ManageResources&SystemName=AnswerBank
data={
   "operation": "add",
   "type":"question",
   "questions":[
      {"text":"Where do I sign up for the monthly newsletter?"}
   ]
}

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

The action returns a question_id, which you can use to create and update question equivalence classes and add answers.

Find the Likelihood of Existing Answers

When you add new questions to your Answer Bank Agentstore, you can find out whether there are any likely answers in your existing question equivalence classes.

The answer likelihood score field for a particular question stores the likelihood that there is an existing answer. Answer Server uses the question text to query your question equivalence classes, and uses the relevance score of each question equivalence class that returns in the query to calculate the likelihood score.

You can use this score to sort questions by likelihood in the GetResources action. See GetResources.

Periodically, Answer Server runs a background process to calculate the likelihood scores for all the questions in the Answer Bank Agentstore that do not have an answer, and updates the field for those questions.

By default, this process runs every 600 seconds (ten minutes). You can use the UpdateLikelihoodInterval configuration parameter in your Answer Bank system configuration to change how frequently to update the likelihood score field.

You can update the field more frequently if you need up-to-date information to sort by likelihood. However, for performance reasons OpenText recommends that you do not update the likelihood score field too frequently, because it might result in a large number of indexing operations in the Answer Bank Agentstore component.

You can set UpdateLikelihoodInterval to a higher value if your question equivalence classes do not change very often, or if do not intend to use the likelihood scores very often.

For more information about UpdateLikelihoodInterval and the GetResources sort options, refer to the Answer Server Reference.

####### Find the Likely Answers to a Question

You can use the GetResources action to filter the list of question equivalence classes to those that are likely to provide an answer for a particular question or set of questions, by using the likely_answer_for filter. This filter matches question equivalence classes where the answer is most relevant to the specified questions.

For example:

action=GetResources&type=question_equivalance_class&filter={ "likely_answer_for": [ {"ids":[ "2373534828452857425" ], "resource_type":"question"} ] }

For more information, refer to the Answer Server Reference.

Question Equivalence Rules

The question equivalence rule provides a general expression to match several equivalent questions. The rule forms part of a question equivalence class. When you ask a question, Answer Server matches the question text against the rules in your question equivalence classes.

In general, you use text with a Boolean or proximity expression to match questions.

For example, the questions Why is the sky blue?, What causes the sky to appear blue?, and What gives the sky the color blue? are all equivalent. You might use the rule sky NEAR blue to match all these questions.

You can expand the rules to more complicated expressions to match more complicated sets of equivalent questions. The expression can use the same Boolean and proximity syntax as the Content component query text, along with bracketed expressions to specify priority. For more information, refer to the Content Component Help.

NOTE: You cannot use Wildcard expressions in your question equivalence rules unless there is also a non-Wildcard term required by the rule. For example, you cannot use the rule sk*, because it contains only a Wildcard term. However, you can use sk* AND blue, because blue is also required. Answer Server returns an error if you try to use an invalid rule.

In general, OpenText recommends that you do not use Wildcard expressions in your rules.

In all these cases, you add the rule to the question equivalence class by using the ManageResources action. The add and update operations for question equivalence classes accept a rule property, which accepts the expression as a string value. For example:

"rule":"sky NEAR blue",

For these rules, you can use the GetResources action to suggest rules. See Generate a Question Equivalence Rule. You can also use the TestRule action to test whether a rule matches all the questions you want. See Test Your Question Equivalence Rule

For more information about adding a rule to a question equivalence class, see Create a Question Equivalence Class and Add an Answer and Update a Question Equivalence Class.

Special Rule Types

In certain special cases, you might also want to use a FieldText expression. This option is most useful when you have a very short question that you want to match exactly. In this case, you can use a FieldText expression to prevent the rule from matching any longer question that contains your short question.

For example, the question What is life? is very short, and might easily match longer questions that are not equivalent, such as What is Life of Pi about?.

When you want to use a FieldText expression when you add or update a question equivalence class, you set the rule property as an object. This object has a required text property, and an optional fieldtext property, which set the appropriate text and FieldText rules.

The Ask action sends the question to your Answer Bank Agenstore in a DRECONTENT field. You can use your FieldText expression to match text in this field by using the Content component FieldText operators.

For example:

"rule": { "text": "What is Life?", "fieldtext": "MATCH{What is Life?}:DRECONTENT" }

This rule matches only the exact question What is life?

For more information about FieldText operators, refer to the Content Component Help.

NOTE: You must always specify the text property. That is, you cannot create a rule with only FieldText.

The more complicated rule types can be useful in certain circumstances. However, the GetResources rule suggestion option does not return any suggestions that contain FieldText. Similarly, you cannot test complex FieldText rules by using the TestRule action.

Generate a Question Equivalence Rule

You can use the GetResources action to suggest a question equivalence rule, based on a set of questions. You can use this to automatically generate an initial question equivalence rule, which you can modify to optimize the rule for your question equivalence class.

For example:

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=rule_suggestion&IDs=9706856188043740111,8129920660480699726,3067998369792637739

This example generates a rule that matches the questions with the IDs 9706856188043740111, 8129920660480699726, and 3067998369792637739.

You can also optionally add additional questions in a text filter, for example to specify the reference question for the question equivalence class that you want to create, or to include questions that do not currently exist in the Answer Bank index.

For example:

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=rule_suggestion&IDs=9706856188043740111,8129920660480699726,3067998369792637739&Filter=%7B%20%22rule_suggestion_text%22%20%3A%20%5B%22How%20do%20I%A0get%20regular%20updates%20about%20MyCompany%3F%22%5D%20%7D

The Filter parameter takes a percent-encoded JSON object, which contains the filters to apply. In this case, the unencoded JSON object is:

{ "rule_suggestion_text" : ["How do I get regular updates about MyCompany?"] }

TIP: You can also use GetResources to find question equivalence classes that do not have an associated rule, by setting the Type parameter to question_equivalence_class, and using the Filter parameter to search for the incoming state (which is for classes that do not have rules). For example:

Action=GetResources&SystemName=MyAnswerbank&Type=question_equivalence_class&Filter=%7B%20%22state%22%3A%20%22incoming%22%20%7D

This corresponds to the following filter:

{ "state" : "incoming" }

You can modify the question equivalence rule as required, and add it to the question equivalence class by using the ManageResources action. See Update a Question Equivalence Class.

You can also test that the question equivalence rule matches all the rules that you want to add to the question class by using the GetResources action. See Test Your Question Equivalence Rule.

Test Your Question Equivalence Rule

When you create a question equivalence rule, you can check that it matches all the questions that you want to include in the question equivalence class, and that it does not match questions that belong to other question equivalence classes. The GetResources action has several filters that you can use to test your rules.

You can also use the TestRule action to test whether a particular set of questions matches a rule that you specify. In this case, you do not need to have indexed the questions or the question equivalence rule.

NOTE: The TestRule action can test only rules that use simple text (with any Boolean and proximity expressions). You cannot test FieldText rules in this way. For more information about FieldText rules, see Special Rule Types.

####### Find Questions that Do Not Match the Rule

You can add the question equivalence rule text as a text filter in GetResources, to find questions that match or do not match the rule. You can also specify a list of IDs for questions that you want to match the rule in the IDs parameter.

TIP: You can retrieve a list of question IDs and the rule for a question equivalence class by sending a GetResources action with Type set to question_equivalence_class.

To test whether the rule matches the questions in the question equivalence class, set the text filter to NOT(RuleText), and set IDs to a list of IDs of the questions in that class.

For example:

http://localhost:12000?Action=GetResources&Type=question&IDs=9706856188043740111,8129920660480699726,3067998369792637739&Filter=%7B%20%22text%22%20%3A%20%22NOT(updates%20AND%C2%A0MyCompany)%22%20%7D

The Filter parameter takes a percent-encoded JSON object, which contains the filters to apply. In this case, the unencoded JSON object is:

{ "text" : "NOT(updates AND MyCompany)" }

This action returns any questions in the list of IDs that do not match the question equivalence rule updates AND MyCompany.

####### Find Questions in Other Classes that Match the Rule

After you create the question equivalence class and add the rule, you can also use GetResources to find out if your rule matches any questions that do not belong to the class, by using the not_associated_with filter.

For example, for a GetResources action with Type set to question, the following filter object matches questions that match the rule updates AND MyCompany, and that do not belong to the question equivalence class with ID 1429393462892614629.

{ 
   "text" : "updates AND MyCompany",
   "not_associated_with": [
      {
         "ids": [
            "1429393462892614629"
         ],
         "type": "question_equivalence_class"
      }
   ]
}

This filter returns questions that match the rule that already belong to a different question equivalence class. This might indicate that your rule is not restrictive enough.

TIP: This filter also returns any questions that match the rule and that do not belong to a question equivalence class. If you want to find only questions that belong to a different question equivalence class, you can add an additional state filter to find questions in the answered state.

####### Test Whether Questions Match a Specified Rule

You can use the TestRule action to test questions and rules that you have not added to the Answer Bank Agentstore. This action allows you to test rules and questions before you index them, to save indexing time, and reindexing time if you need to change the rule.

To use TestRule, you specify the questions in a JSON object in the Questions parameter, and the rule in the Rule parameter. You must also set SystemName to the name of the Answer Bank system.

For example:

action=TestRule&SystemName=MyAnswerBank&Questions={"text":["Why is the sky blue?","What causes the sky to appear blue?","How do I return a defective item?"],"ids":["7660794084496396635","15927917885427259786","14042282250303108454"]}&Rule=sky AND blue

This action tests whether the questions Why is the sky blue?, What causes the sky to appear blue?, and How do I return a defective item?, and the questions with IDs 7660794084496396635, 15927917885427259786, and 14042282250303108454 match the rule sky AND blue.

The action returns the rule, with a matched property that contains the list of matching questions, and the not_matched property that contains any questions in the request that do not match the rule.

{
   "rule": "sky AND blue",
   "matched": {
      "text": [
         "Why is the sky blue?",
         "What causes the sky to appear blue?"
      ],
      "id" [
         "15927917885427259786",
         "14042282250303108454"
      ]
   },
   "not_matched": {
      "text": [
         "How do I return a defective item?"
      ],
      "id": [
        "7660794084496396635"
      ]
   }
}

Check Spelling for Question Equivalence Rules

Answer Server can check the spelling of the rules you submit to the TestRule action. When you configure this, a corrected rule might be returned in the spellchecked_rule element of the response. This correction is not used by the Answer Bank system (Answer Server always uses the rule that you supply), but if appropriate you can resend the action with the corrected rule.

To check spelling you must have an Content component that contains a large amount of indexed documents. With a sufficiently large amount of data spelling errors can be identified.

To check spelling

Open your configuration file in a text editor.

Create a new section in the configuration file and configure a spelling checker. You can give the section any name. Set the following parameters:


Type	The type of component to use to check spelling. Set this parameter to `Content`.
Host	The host name or IP address of the machine hosting the Content component.
ACIPort	The ACI port of the Content component.
LanguageType	The value to use for the `LanguageType` parameter, in `Query` actions sent to the Content component.

For example:

[MySpellingChecker]
Type=Content
Host=localhost
ACIPort=12345
LanguageType=englishUTF8

For more information about these configuration parameters, refer to the Answer Server Reference.

Find the configuration section for the Answer Bank system. In this section, set the configuration parameter SpellcheckEngine to the name of the section that you created in the previous step. For example:
```
[MyAnswerBankSystem]  
SpellcheckEngine=MySpellingChecker
```
Restart Answer Server for your configuration changes to take effect.

Create a Question Equivalence Class and Add an Answer

A question equivalence class is a group of equivalent questions. When you have multiple questions with different wording that request the same information, you can combine these questions in a question equivalence class. You also use the question equivalence class to add an answer.

The question equivalence class contains the following information:

the reference question (a standard question that is the most representative question for the answer).
the answer to the reference question.
a list of real, sample questions that are equivalent to the reference question. These questions are stored by adding a question. See Add a Question.
a question equivalence rule that matches the equivalence question. When a user asks a question, Answer Server uses the question equivalence rule to find a relevant question equivalence class to match. See Question Equivalence Rules.

To create question equivalence classes, you use a ManageResources action, with the information about the questions provided in the Data parameter as a JSON object.

NOTE: When you add a question to a question equivalence class, Answer Server automatically updates the question state to answered. You cannot delete a question in this state, and you cannot manually move the question out of this state. You must remove the question from the question equivalence class. See Update a Question Equivalence Class.

You must include the question_id values for the questions that you want to include in the question equivalence class. You can retrieve the question_id values by sending a GetResources action. For example:

http://localhost:12000?Action=GetResources&SystemName=Answerbank&Type=question

You can add multiple question equivalence classes in the same operation, where each question equivalence class is an object in an array.

You can also add a context to a question equivalence class. This information will be returned in the ask response to be used with a future ask action using the same managed context. See Use Context in the Ask Action

The following example adds a single question equivalence class that combines two questions, adds a reference question and an answer, and adds a context. You can also add optional metadata for the answer, such as author information.

Action=ManageResources&SystemName=AnswerBank
data={
   "operation":"add",
   "type":"question_equivalence_class",
   "question_equivalence_classes":[
      {
         "question_ids":[
            "9706856188043740111",
            "8129920660480699726"
         ],
         "rule":{"text":"how AND (regular NEAR2 updates) AND MyCompany"},
         "answer":{
            "text":"Send an email to [email protected], and we'll add you to our monthly newsletter.",
            "metadata":[
               {"key":"author", "value":"Alex"},
               {"key":"modified_date", "value":"2017-05-05"}
            ]
         },
         "reference_question":"How do I get regular updates about MyCompany?",
         "context": ["MyCompany"]
      }
   ]
}

NOTE: Metadata key names can contain alphanumeric characters (a-z, 0-9), period (.), underscore (_) and hyphen (-). They cannot start with a number. It is also best practice to use field names that conform to XML specifications.

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

You can also use the GetResources action to generate a rule for your question equivalence class. See Generate a Question Equivalence Rule.

Update a Question Equivalence Class

You can update the following properties in your question equivalence classes:

the list of question IDs that the question equivalence class contains.
the answer to the reference question.
the question equivalence rule.
the text of the reference question. In general, OpenText recommends you use this update to correct spelling mistakes only. If you want to completely change the reference question, create a new question equivalence class with a new ID.

To update a question equivalence class, you use a ManageResources action in a POST request method, with the information about the questions provided in the Data parameter as a JSON object.

The update operation replaces existing content with the new version that you provide. If you omit a value, Answer Server keeps the existing value. If you want to delete the existing value, you can explicitly set an empty value or array.

For example, if you change the list of question IDs, but do not set the answer block in your JSON data, Answer Server updates the list of questions, but does not modify the answer.

The amend operation allows you to add questions to the question equivalence class. In this case, you provide only the questions that you want to add to the question equivalence class, rather than the complete list of question IDs. You can use this option if you might have multiple users adding equivalent questions at the same time, to ensure that all changes are reflected.

NOTE: When you add questions to a question equivalence class, Answer Server automatically updates the question state to answered. If you remove all questions from the question equivalence class, it reverts the question state to incoming.

The following example updates the question equivalence class with ID 2012912839742797651 with a new list of question_ids. It does not update the stored answer for the question (if it exists).

Action=ManageResource&SystemName=AnswerBank
data={
   "operation":"update",
   "type":"question_equivalence_class",
   "question_equivalence_class":{
      "id": 2012912839742797651,
      "question_ids":[
         "9706856188043740111",
         "8129920660480699726",
         "3067998369792637739"
      ],
      "reference_question":"How do I get regular updates about MyCompany?",
      "rule": "updates AND MyCompany"
   }
}

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

You can also use the GetResources action to generate a rule for your question equivalence class. See Generate a Question Equivalence Rule.

Update the Question State

The questions in your Answer Bank systems have a state, which can have one of the following values:

incoming
answerable
needs_answer
answered
rejected

Answer Server makes some changes to the question state automatically. You an also modify the question state manually by using the ManageResources action.

####### Automatic Question State Updates

When you add a question to the Answer Bank, Answer Server automatically assigns it the state incoming.

When you add the question to a question equivalence class, the state automatically updates to answered.

Similarly, if you remove the question from the question equivalence class (or if you delete the question equivalence class), the state reverts to incoming. If you later undelete the question equivalence class that the question belongs to, the question returns to answered again.

####### Update the Question State Manually

You can modify the state of a question by using the ManageResources action, with the update operation, either as part of another update, or as a separate action.

NOTE: You cannot manually change the state to or from answered by using a question update. To move the question to the answered state, you must add the question to a question equivalence class.

You must include the question IDs for the questions that you want to update. You can retrieve the question ID by sending a GetResources action. For example:

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question

The following example updates the questions with IDs 9706856188043740111 and 8129920660480699726 to have the state needs_answer.

Action=ManageResources&SystemName=AnswerBank
data={
   "operation": "update",
   "type": "question",
   "question": { 
      "question_ids": [
         "9706856188043740111",
         "8129920660480699726"
      ], 
   "new_state": "needs_answer"
   }
}

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

You can use the question state to filter questions in the GetResources action. You can also use the GetStats action to return information about the questions in the Answer Bank system by state. For more information, see Retrieve the Information Stored in an Answer Bank.

Update the Question State

The questions in your Answer Bank systems have a state, which can have one of the following values:

incoming
answerable
needs_answer
answered
rejected

Answer Server makes some changes to the question state automatically. You an also modify the question state manually by using the ManageResources action.

####### Automatic Question State Updates

When you add a question to the Answer Bank, Answer Server automatically assigns it the state incoming.

When you add the question to a question equivalence class, the state automatically updates to answered.

####### Update the Question State Manually

You can modify the state of a question by using the ManageResources action, with the update operation, either as part of another update, or as a separate action.

NOTE: You cannot manually change the state to or from answered by using a question update. To move the question to the answered state, you must add the question to a question equivalence class.

You must include the question IDs for the questions that you want to update. You can retrieve the question ID by sending a GetResources action. For example:

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question

The following example updates the questions with IDs 9706856188043740111 and 8129920660480699726 to have the state needs_answer.

Action=ManageResources&SystemName=AnswerBank
data={
   "operation": "update",
   "type": "question",
   "question": { 
      "question_ids": [
         "9706856188043740111",
         "8129920660480699726"
      ], 
   "new_state": "needs_answer"
   }
}

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

Update the Question State

The questions in your Answer Bank systems have a state, which can have one of the following values:

incoming
answerable
needs_answer
answered
rejected

Answer Server makes some changes to the question state automatically. You an also modify the question state manually by using the ManageResources action.

####### Automatic Question State Updates

When you add a question to the Answer Bank, Answer Server automatically assigns it the state incoming.

When you add the question to a question equivalence class, the state automatically updates to answered.

####### Update the Question State Manually

You can modify the state of a question by using the ManageResources action, with the update operation, either as part of another update, or as a separate action.

NOTE: You cannot manually change the state to or from answered by using a question update. To move the question to the answered state, you must add the question to a question equivalence class.

You must include the question IDs for the questions that you want to update. You can retrieve the question ID by sending a GetResources action. For example:

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question

The following example updates the questions with IDs 9706856188043740111 and 8129920660480699726 to have the state needs_answer.

Action=ManageResources&SystemName=AnswerBank
data={
   "operation": "update",
   "type": "question",
   "question": { 
      "question_ids": [
         "9706856188043740111",
         "8129920660480699726"
      ], 
   "new_state": "needs_answer"
   }
}

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

Delete a Question or Question Equivalence Class

You can use the ManageResources action to delete a question or a question equivalence class.

After you delete an item, there is a short period in which you can undelete it, before it is permanently deleted from the system. See Undelete a Question or Question Equivalence Class.

To delete a question or question equivalence class, you use a ManageResources action in a POST request method, with the information about the item that you want to delete provided in the Data parameter as a JSON object.

You must include the ID of the item that you want to delete, and set the type of the operation to question or question_equivalence_class, as appropriate.

NOTE: You cannot delete a question that has the state answered (that is, a question that belongs to a question equivalence class). You must remove it from the question equivalence class before you delete it. See Update the Question State and Update a Question Equivalence Class.

You can retrieve the ID of the question or question equivalence class by sending a GetResources action. For example:

http://localhost:12000?Action=GetResources&SystemName=Answerbank&Type=question_equivalence_class

The following example deletes a question equivalence class.

Action=ManageResource&SystemName=AnswerBank
data={
   "operation":"delete",
   "type":"question_equivalence_class",
   "ids": [ 
      "2012912839742797651"
   ]
}

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

Undelete a Question or Question Equivalence Class

After you delete a question or question equivalence class, there is a short period in which you can undelete it before it is permanently deleted from the system. For more information about how long an item is available after you delete it, see Modify the Expiration Time.

To undelete a question or question equivalence class, you use a ManageResources action in a POST request method, with the information about the item that you want to undelete provided in the Data parameter as a JSON object.

You must include the ID of the item that you want to undelete, and set the type of the operation to question or question_equivalence_class, as appropriate.

You can retrieve the ID of the question or question equivalence class by sending a GetResources action. For example:

http://localhost:12000?Action=GetResources&SystemName=Answerbank&Type=question_equivalence_class

The following example restores a question equivalence class:

Action=ManageResource&SystemName=AnswerBank
data={
   "operation":"undelete",
   "type":"question_equivalence_class",
   "ids": [ 
      "2012912839742797651"
   ]
}

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

####### Modify the Expiration Time

When you delete a question or question equivalence class, Answer Server uses ExpireDateType fields in the Answer Bank Agentstore component to manage the expiration of deleted items.

All items in the Answer Bank Agentstore have an ExpireDateType field. Normally, these fields are set such that the questions and question equivalence classes never expire. When you delete an item, Answer Server sets this expiration time to a short time after you delete it.

By default, the expiration time is ten minutes. The default Answer Bank Agentstore configuration runs an expiration schedule every hour. You can therefore expect your question and question equivalences classes to be available to undelete for between ten minutes and an hour and ten minutes.

To change the expiration time that Answer Server assigns to deleted items, modify the UndeleteLifetime configuration parameter in the section of the Answer Server configuration file where you configure the Answer Bank system. For more information, refer to the Answer Server Reference.
To change the expiration schedule, modify the ExpireTime configuration parameter in the [Schedule] section of the Answer Bank Agentstore configuration file. For more information refer to the Content Component Help.

Undelete a Question or Question Equivalence Class

You must include the ID of the item that you want to undelete, and set the type of the operation to question or question_equivalence_class, as appropriate.

You can retrieve the ID of the question or question equivalence class by sending a GetResources action. For example:

http://localhost:12000?Action=GetResources&SystemName=Answerbank&Type=question_equivalence_class

The following example restores a question equivalence class:

Action=ManageResource&SystemName=AnswerBank
data={
   "operation":"undelete",
   "type":"question_equivalence_class",
   "ids": [ 
      "2012912839742797651"
   ]
}

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

####### Modify the Expiration Time

When you delete a question or question equivalence class, Answer Server uses ExpireDateType fields in the Answer Bank Agentstore component to manage the expiration of deleted items.

To change the expiration time that Answer Server assigns to deleted items, modify the UndeleteLifetime configuration parameter in the section of the Answer Server configuration file where you configure the Answer Bank system. For more information, refer to the Answer Server Reference.
To change the expiration schedule, modify the ExpireTime configuration parameter in the [Schedule] section of the Answer Bank Agentstore configuration file. For more information refer to the Content Component Help.

Check the Status of an Update

The GetJobStatus action allows you to check the status of jobs in your ManageResources actions.

For example:

action=GetJobStatus&SystemName=MyAnswerBank&JobTokens=41,42,43

This action returns the status of the jobs with job IDs 41, 42, and 43.

Store Statistics for Your Answer Bank

You can configure Answer Server to store some information about the usage of your Answer Bank question equivalence classes in an ODBC-compatible database.

When you configure statistics storage, Answer Server stores popularity information for your question equivalence classes. Each time the text of an Ask action matches a question equivalence class, Answer Server updates the database.

Periodically, Answer Server also queries the database for the popularity information, and uses it to update a count field in the question equivalence class. You can use this field to sort question equivalence classes by popularity in the GetResources action.

To configure Answer Bank to store statistics

Open your configuration file in a text editor.
Find the configuration section for the Answer Bank system for which you want to store statistics.
In this configuration section, set StatsStorage to the name of a configuration section for the statistics database details. For example:
```
[MyAnswerBank]  
StatsStorage=MyStatsDB
```
(Optional) Set UpdatePopularityInterval to the number of seconds between updates of the question popularity field in the Answer Bank Agentstore.

By default, Answer Server updates the field every 600 seconds (10 minutes).

You can update the field more frequently if you need up-to-date information to sort by popularity. However, for performance reasons OpenText recommends that you do not update the popularity count field too frequently, because it might result in a large number of indexing operations in the Answer Bank Agentstore component.
(Optional) Set PopularityWindowDays to the number of days for which you want to consider popularity information for your question equivalence classes in the Answer Bank Agentstore.

By default, Answer Server stores the count for the last seven days. That is, each time Answer Server updates the popularity field, it stores the number of times the question equivalence class was matched in the last week.
Create a configuration section for the statistics database. The name of this section must match the section you defined in the StatsStorage parameter in step 3. For example:
```
[MyStatsDB]
```
In the statistics database configuration section, set ConnectionString to the connection string to use to connect to the statistics database. Answer Server passes this string on to the database, so you can use a connection string that works in any SQL client application. For example:
```
[MyStatsDB]
ConnectionString=Driver=PostgreSQL ANSI(x64); Server=sql-host.mycompany.com; Port=5432; Database=statsdb; Uid=postgres;password=password;
```
The database that you configure must exist, but Answer Server creates all the tables that it needs to store the statistics information. The database must also be able and configured to accept dates in ISO-8601 formats (that is, YYYY-MM-DD hh:mm:ss).

NOTE: On Linux operating systems, remove the spaces in the connection string.
(Optional) Set Enabled to True. The default value for this parameter is True, but you might want to set it explicitly for clarity. You can set Enabled to False if you want to stop storing the statistics.

The following example shows the complete configuration for this statistics database.

[MyAnswerBank]  
StatsStorage=MyStatsDB
UpdatePopularityInterval=600
PopularityWindowDays=7

[MyStatsDB]
Enabled=True
ConnectionString=Driver=PostgreSQL ANSI(x64); Server=sql-host.mycompany.com; Port=5432; Database=statsdb; Uid=postgres;password=password;

Retrieve the Information Stored in an Answer Bank

The GetResources and GetStats actions allow you to retrieve the information in your Answer Bank systems.

GetResources

The GetResources action allows you to retrieve the questions, answers, question equivalence classes, schemas, and XSDs for your answer systems. You can retrieve information for all systems by type, or you can restrict to a subset of systems or resource IDs, or exclude a particular set of IDs. You can also apply a filter to restrict the results to those that match some text, or a particular question state.

Examples

The following action retrieves the schemas to use in a ManageResources action:

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=schema

The following action retrieves the first ten question equivalence classes stored in the specified Answer Bank system.

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question_equivalence_class

The following action retrieves the questions in the specified Answer Bank system that contain the keyword President in the question text or rule.

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question&Filter=%7B%20%22text%22%3A%20%22president%22%20%7D

The following action retrieves the questions in the specified Answer Bank system that have not been answered (incoming, answerable, and needs_answer states).

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question&Filter=%7B%20%22state%22%3A%20%5B%22incoming%22%2C%20%22answerable%22%2C%20%22needs_answer%22%5D%20%7D

The following action returns the question equivalence class with ID 4371920660452849522.

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question_equivalence_class&IDs=4371920660452849522

The following action returns the response XML Schema Definitions (XSDs) for the Answer Server actions:

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=XSD

For more examples of how to use GetResources to find particular information, see Manage an Answer Bank.

GetStats

The GetStats action returns information about the number of questions and question equivalence classes with each question state (incoming, answered, and so on). For example, you can use this action to find out if you have any unanswered questions in the system.

For full details about the parameters available in the GetStats action, refer to the Answer Server Reference.

Example

action=GetStats&SystemName=MyAnswerBank

Retrieve the Information Stored in an Answer Bank

The GetResources and GetStats actions allow you to retrieve the information in your Answer Bank systems.

GetResources

Examples

The following action retrieves the schemas to use in a ManageResources action:

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=schema

The following action retrieves the first ten question equivalence classes stored in the specified Answer Bank system.

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question_equivalence_class

The following action retrieves the questions in the specified Answer Bank system that contain the keyword President in the question text or rule.

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question&Filter=%7B%20%22text%22%3A%20%22president%22%20%7D

The following action retrieves the questions in the specified Answer Bank system that have not been answered (incoming, answerable, and needs_answer states).

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question&Filter=%7B%20%22state%22%3A%20%5B%22incoming%22%2C%20%22answerable%22%2C%20%22needs_answer%22%5D%20%7D

The following action returns the question equivalence class with ID 4371920660452849522.

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question_equivalence_class&IDs=4371920660452849522

The following action returns the response XML Schema Definitions (XSDs) for the Answer Server actions:

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=XSD

For more examples of how to use GetResources to find particular information, see Manage an Answer Bank.

GetStats

For full details about the parameters available in the GetStats action, refer to the Answer Server Reference.

Example

action=GetStats&SystemName=MyAnswerBank

Retrieve the Information Stored in an Answer Bank

The GetResources and GetStats actions allow you to retrieve the information in your Answer Bank systems.

GetResources

Examples

The following action retrieves the schemas to use in a ManageResources action:

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=schema

The following action retrieves the first ten question equivalence classes stored in the specified Answer Bank system.

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question_equivalence_class

The following action retrieves the questions in the specified Answer Bank system that contain the keyword President in the question text or rule.

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question&Filter=%7B%20%22text%22%3A%20%22president%22%20%7D

The following action retrieves the questions in the specified Answer Bank system that have not been answered (incoming, answerable, and needs_answer states).

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question&Filter=%7B%20%22state%22%3A%20%5B%22incoming%22%2C%20%22answerable%22%2C%20%22needs_answer%22%5D%20%7D

The following action returns the question equivalence class with ID 4371920660452849522.

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=question_equivalence_class&IDs=4371920660452849522

The following action returns the response XML Schema Definitions (XSDs) for the Answer Server actions:

http://localhost:12000?Action=GetResources&SystemName=MyAnswerbank&Type=XSD

For more examples of how to use GetResources to find particular information, see Manage an Answer Bank.

GetStats

For full details about the parameters available in the GetStats action, refer to the Answer Server Reference.

Example

action=GetStats&SystemName=MyAnswerBank

Set Up a Fact Bank System

A Fact Bank system requires a Fact Store subcomponent, which is usually a SQL database. You can also configure Fact Bank to use a Lua script to retrieve facts from an external fact store.

Fact Bank also requires question parser Named Entity Recognition grammar files, and a set of coding files. You can optionally configure additional Named Entity Recognition grammars for advanced time normalization. Advanced time normalization extracts dates and times in various formats from questions and normalize them to a consistent format, to improve fact retrieval.

You must download and install the Fact Store component separately, and update the configuration with any Answer Server-specific configurations.

The following sections describe how to configure and set up your Fact Store and Named Entity Recognition grammars, and how to configure the coding files.

Configure the Fact Bank System

The Answer Server configuration file contains information about the subcomponents in your Fact Bank systems.

For any Fact Bank system, you must configure the name of your Question Parser and time normalization Named Entity Recognition grammars and Lua scripts, and the locations of the Fact Bank coding files. You must also configure the Fact Store.

You can optionally also configure a second Named Entity Recognition grammar for advanced time normalization. Advanced time normalization extracts dates and times in various formats from questions and normalize them to a consistent format, to improve fact retrieval.

The Fact Store component stores the facts that you want to be able to retrieve. The Fact Store content is structured data, containing the entities and properties for your facts. As such, OpenText recommends that you use a SQL database as the backend component for your fact store, because it is optimized for querying structured content.

Alternatively, you can use a Lua script to retrieve facts from an external fact store.

You specify the type of Fact Store that you want to use by configuring the BackendType configuration parameter in the system configuration section in the Answer Server configuration file. Depending on which back end type you choose, you must also set additional configuration parameters.

The following sections describe how to configure the Fact Bank system in Answer Server, depending on the type of Fact Store you choose.

Configure a Fact Bank with a SQL Database Fact Store

The following procedure describes the Answer Server configuration you need to set up a Fact Bank system with a SQL database back end. For information about how to set up the SQL database, see Set Up a SQL Backend as Fact Store.

To configure the Fact Bank System for a SQL database backend

Open the Answer Server configuration file in a text editor.
Find the [Systems] section, or create one if it does not exist. This section contains a list of systems, which refer to the associated configuration sections for each system.
After any existing systems, add an entry for your new Fact Bank system. For example:
```
[Systems]
0=MyAnswerBank
1=MyFactBank
```
Create a configuration section for your Fact Bank system, with the name that you specified. For example, [MyFactBank].
Set Type to FactBank.
Set BackendType to sqldb.
Set ConnectionString to the connection string to use to connect to the RDBMS that contains the fact store content.
Set EductionQuestionGrammars to the name of your question parser grammar. You can also optionally set EductionEntities to a list of entities to use from the specified grammars.
Set EductionTimeGrammars to the name of the Named Entity Recognition grammar to use for advanced time normalization. You can also optionally set TimeEntities to a list of entities to use from the specified grammars.
Set EductionLuaScript and TimeLuaScript to the file name and path to the Lua scripts to use for question parsing and time normalization.
Specify how Fact Bank must access your coding files by using one of the following methods:
- To use coding text files (see Create Coding Files):
  1. Set CodifierType to files.
  2. Set CodingsPath and CodingsDatPath to the locations of the coding files.
- To use a coding database (see Set up a SQL Database for Coding Information):
  1. Set CodifierType to odbc.
  2. Set CodingsConfigSection to the name of a configuration section where you define the connection information your coding database.
  3. Create the corresponding configuration section for the coding database (for example [FactBankCodings0]).
  4. In this coding database configuration section, set ConnectionString to the connection string to use to connect to the RDBMS that contains the coding information.
(Optional) Set the parameter AskParallelizationFactor to specify the number of threads to use to gather answers (for each Ask action). The default value is 1 but if your Answer Server has sufficient resources you can improve response times by increasing the number.
Save and close the configuration file.
Restart Answer Server for your changes to take effect.

For example:

[MyFactBank]
Type=factbank
AskParallelizationFactor=4
// Question Parser
EductionQuestionGrammars=./resources/grammars/question_grammar_en.ecr
EductionLuaScript=./resources/lua/question_grammar_en.lua
EductionTimeGrammars=./resources/grammars/datetime_processing.ecr
TimeLuaScript=./resources/lua/datetime.lua
// Fact Store
BackendType=sqldb
ConnectionString=Driver={PostgreSQL};Server=sql-host.mycompany.com;Port=5432;Database=factstoredb;Uid=postgres;password=password;
// Coding Files
CodingsPath=./codings
CodingsDatPath=./codings

Configure a Fact Bank to Call a Lua Script

The following procedure describes the Answer Server configuration you need to set up a Fact Bank system to call a Lua script to retrieve facts. For information about how to write the script, see Use a Lua Scripts to Retrieve Facts and the Answer Server Reference.

To configure the Fact Bank system for a Lua Script backend

Open the Answer Server configuration file in a text editor.
Find the [Systems] section, or create one if it does not exist. This section contains a list of systems, which refer to the associated configuration sections for each system.
After any existing systems, add an entry for your new Fact Bank system. For example:
```
[Systems]
0=MyAnswerBank
1=MyFactBank
```
Create a configuration section for your Fact Bank system, with the name that you specified. For example, [MyFactBank].
Set Type to FactBank.
Set BackendType to Lua.
Set ScriptPath to the path to the Lua script that you want to run as your Fact Bank. Answer Server calls out to this script whenever it processes an Ask action that includes the Lua Fact Bank system, and returns the response as an answer.
(Optional) Set ScriptFunction to the entry function in your Lua script that Answer Server must call. The default entry function is called fetch.
Set EductionQuestionGrammars to the name of your question parser grammar. You can also optionally set EductionEntities to a list of entities to use from the specified grammars.
Set EductionTimeGrammars to the name of the Named Entity Recognition grammar to use for advanced time normalization. You can also optionally set TimeEntities to a list of entities to use from the specified grammars.
Set EductionLuaScript and TimeLuaScript to the file name and path to the Lua scripts to use for question parsing and time normalization.
Specify how Fact Bank must access your coding files by using one of the following methods:
- To use coding text files (see Create Coding Files):
  1. Set CodifierType to files.
  2. Set CodingsPath and CodingsDatPath to the locations of the coding files.
- To use a coding database (see Set up a SQL Database for Coding Information):
  1. Set CodifierType to odbc.
  2. Set CodingsConfigSection to the name of a configuration section where you define the connection information your coding database.
  3. Create the corresponding configuration section for the coding database (for example [FactBankCodings0]).
  4. In this coding database configuration section, set ConnectionString to the connection string to use to connect to the RDBMS that contains the coding information.
(Optional) Set the parameter AskParallelizationFactor to specify the number of threads to use to gather answers (for each Ask action). The default value is 1 but if your Answer Server has sufficient resources you can improve response times by increasing the number.
Save and close the configuration file.
Restart Answer Server for your changes to take effect.

Configure the Fact Store

Alternatively, you can use a Lua script to retrieve facts from an external fact store.

The following sections describe how to set up the Fact Store backend.

Set Up a SQL Backend as Fact Store

You can use a SQL database to store facts and qualifiers for your Fact Store.

Answer Server can connect to any RDBMS that supports SQL. You specify how to connect to the database by setting the appropriate connection string in the ConnectionString configuration parameter in the FactBank configuration. The most fully tested options are:

SQLite
PostgreSQL (version 9.3 or later is required)

The SQL Fact Store has two required tables, one for facts, and one for qualifiers. The facts table stores the values of entity properties. The qualifiers table stores the names and values of particular sets of qualifiers associated with the properties. Each table includes qualifier combination values, which link the properties to the associated qualifiers.

In addition, there are two optional tables, one for sources and one for security types. The sources table stores information about the sources of your facts, including optional security information to allow you to restrict the facts by user permissions. The security types table stores the security configuration information for your security types.

Your Answer Server installation includes PostgreSQL schema files for these tables, and a utility script that you can use to apply these schemas to a database by using the psql utility. These files are available in the /factbank/schemas/postgresql directory in your installation.

The following sections describe the tables in more detail, and provide some best practices for how to organize your fact stores.

Manage Your Tables

OpenText recommends that you organize your tables by creating a separate database for each set of facts and qualifiers. In this case, each database is the backend for its own Fact Bank system, which optimizes the database queries required for an Ask action.

For example, if you have a collection of facts about company sales histories, and a collection of facts about the products that a company offers, you might create a sales database and a products database. Each database is a separate Fact Bank instance in your Answer Server setup, and you can easily query one or both, as required.

Facts Table

The facts table stores the values of entity properties.

This table must have the name facts. The facts table has four required columns, and one optional column, described in the following table.

Column	Type	Description
`entity_code`	text	The code for the entity that this row is about, from your `entity_to_code.txt` coding file.
`property_code`	text	The code for the property that this row is about, from your `property_to_code.txt` coding file.
`property_value`	text	The value of this property for the specified entity, in the associated qualifier combination.
`qualifier_combination`	integer	The reference value for the rows in the `qualifiers` table that contain qualifiers that apply to a particular property value. This value corresponds to the values in the `qualifier_combination` column in the `qualifiers` table. Answer Server uses this column to find the appropriate property, entity, or property value when a question contains a particular qualifier. If this value does not correspond to a value in the qualifiers table, Answer Server treats it as having no qualifiers. OpenText recommends that you reserve a value to use for properties that do not have qualifiers (usually 0).
`source_id`	integer	(Optional) The reference value for the row in the `sources` table that contains the source for this fact. This value corresponds to the values in the `id` column in the `sources` table. Answer Server uses this column to find and return the source for a particular fact. If this value is missing, or does not correspond to a value in the sources table, Answer Server returns the source as SQLDB. OpenText recommends that you reserve a value to use for properties that do not have source information (usually 0).

You can optimize the performance of the facts table by creating indexes on each column. For example, in a PostgreSQL instance, OpenText recommends that you create a btree index on each column.

Qualifiers Table

The qualifiers table stores the codes and values for qualifiers, and the qualifier combination reference that links a qualifier to a row in the facts table.

The table must have the name qualifiers. The qualifiers table has three columns, described in the following table.

Column	Type	Description
`qualifier_combination`	integer	The qualifier combination reference that identifies qualifiers that are associated with a particular property value for an entity.
`qualifier_code`	text	The code for the property that this qualifier is about, from your `property_to_code.txt` file
`qualifier_value`	text	The value of the qualifier in this qualifier combination

Most data sets will have multiple rows with the same qualifier combination. For example, if your facts table contains the ares of different types of land in a country over time, you might have something like the following table for qualifiers.

qualifier_combination	qualifier_code	qualifier_value
1	LANDTYPE	Farmland
1	YEAR	2015
2	LANDTYPE	Forest
2	YEAR	2015
3	LANDTYPE	Farmland
3	YEAR	2016
4	LANDTYPE	Forest
4	YEAR	2016

In this case, the qualifier combination 1 relates to farmland in 2015, qualifier combination 2 relates to forest in 2015, and so on.

You can optimize the performance of the qualifiers table by creating indexes on each column. For example, in a PostgreSQL instance, OpenText recommends that you create a btree index on each column.

Sources Table

The sources table is an optional table to allow you to store the sources for your facts. You can use this option with the source_id column in the facts table to store the details of the fact sources. Answer Server returns the source information with the fact when it returns in an Ask action.

The table must have the name sources. The sources table has two required columns and two optional columns, described in the following table.

Column	Type	Description
`id`	integer	A primary key integer ID value for the source.
`source`	text	The name of the source. Answer Server returns this value in the `Ask` action when it returns a fact that has the associated source ID.
`acl`	text	(Optional) The Access Control List (ACL) for this source. You can use this option if you want to use user security for your facts.
`security_type_id`	integer	(Optional) The reference value for the row in the `security_types` table that contains the security type for this source. This value corresponds to the values in the `id` column in the `security_types` table. You can use this option if you want to use user security for your facts. Answer Server uses this column to find and return the security type for a particular source. If this value does not correspond to a value in the `security_types` table, Answer Server treats it as having no security. You can set `security_type_id` to `NULL`, or you might want to reserve a value to use for properties that do not have security (usually 0).

Security_Types Table

The security types table is an optional table to allow you to store the security type information for your sources. You can use this option with the security_type_id column in the sources table to store the details of the security types.

The table must have the name security_types. The security types table has two columns, described in the following table.

Column	Type	Description
`id`	integer	A primary key integer ID value for the security type. This value corresponds to the IDs that you use in the `sources` table.
`friendly_name`	text	The name of the security type. This value must correspond to the security type configuration section in your Answer Server configuration file.

SQL Fact Store Example

The following section describes an example of setting up a SQL backend Fact Bank.

A company wants to make its exports data available for question answering. It exports two products, Psi and Omega, to two countries, Germany and France.

In 2015, Psi cost €5 and Omega cost €20. The company exported:

50 units of Psi and 20 units of Omega to Germany.
10 units of Psi and 30 units of Omega to France.

In 2016, Psi cost €7 and Omega cost €18. Sales increased, and the company exported:

80 units of Psi and 100 units of Omega to Germany.
40 units of Psi and 50 units of Omega to France.

The following tables show the Fact Bank Facts and Qualifiers table for this information.

Facts Table

entity_code	property_code	property_value	qualifier_combination
`QPSI`	`REXPORTS`	50	0
`QPSI`	`REXPORTS`	10	1
`QPSI`	`REXPORTS`	80	2
`QPSI`	`REXPORTS`	40	3
`QOMEGA`	`REXPORTS`	20	0
`QOMEGA`	`REXPORTS`	10	1
`QOMEGA`	`REXPORTS`	80	2
`QOMEGA`	`REXPORTS`	40	3
`QPSI`	`RPRICE`	5	4
`QOMEGA`	`RPRICE`	20	4
`QPSI`	`RPRICE`	7	5
`QOMEGA`	`RPRICE`	18	5

Qualifiers Table

qualifier_combination	qualifier_code	qualifier_value
0	`S.COUNTRY`	Germany
0	`S.YEAR`	2015
1	`S.COUNTRY`	France
1	`S.YEAR`	2015
2	`S.COUNTRY`	Germany
2	`S.YEAR`	2016
3	`S.COUNTRY`	France
3	`S.YEAR`	2016
4	`S.YEAR`	2015
5	`S.YEAR`	2016

The following example shows the entity code values in the code_to_entity.txt file:

QPSI=Psi  
QOMEGA=Omega

The following example shows the property code values in the code_to_property.txt file:

S.YEAR=Year,string
S.COUNTRY=Country,string
RPRICE=Price,string
REXPORTS=Exports,string

You can use this Fact Bank setup to answer questions such as:

What were the 2015 exports of Psi?
How many Omega were exported to Germany?
What is the average price of Omega?

Your Answer Server installation includes example files that allow you to test this setup. The example files are included in the sql_example directory.

To use this example, you must have a PostgreSQL instance (running on PostgresHost and PostgresPort, with a user who has access to a factbank_example database.

To set up the example

Restore the database from the factback_example.pgdump file into your PostgreSQL instance, by using a command of the following form:
```
psql -h PostgresHost -p PostgresPort -U UserName factbank_example < factbank_example.pgdump
```
In your Answer Server configuration file, configure a Fact Bank system to use the plain text coding files provided in the example, by setting the CodingsPath parameter to point to the example coding files. For example:
```
[MyExampleFactBank]
Type=factbank
CodingsPath=C:\AnswerServer\sql_example
...
```
In the Fact Bank system configuration, set the ConnectionString to the appropriate connection string for your example database.
In the Fact Bank system configuration, set the EductionQuestionGrammars parameters to the location of your FactBankEductionGrammar.ecr, which is distributed with Answer Server.
Save and close the configuration file.
Start all the Answer Server components.

You can now use the Ask action to ask the questions listed above and to check the responses.

Use a Lua Scripts to Retrieve Facts

You can configure a Fact Bank system in Answer Server that calls a Lua script to get facts. Answer Server calls out to this script whenever it processes an Ask action that includes the Lua Fact Bank system, and returns the response as an answer.

For example, you might have an external data source or API that contains the factual information. Rather than convert the information into a Fact Store database format, you can use a Lua script to retrieve the information directly.

NOTE: When Answer Server processes a question in an Ask action, it might find multiple ways to parse the question. This might mean that Answer Server calls your script multiple times for a single Ask action, although some of the parsings might not match any available facts.

To use a Lua script, you must ensure that the Fact Bank configuration has the BackendType configuration parameter set to Lua. See Configure a Fact Bank to Call a Lua Script.

Create a Fact Retrieval Script

The Lua script must implement a script function that Answer Server can call. By default, Answer Server calls the fetch function, but you can use a different name and set the ScriptFunction configuration parameter to the appropriate function name.

The script function must accept a single LuaIncompleteFact object, and return an array of LuaCodifiedFact objects.

For example, the following fetch function always returns an empty array:

function fetch(incomplete)
  return {}
end

The LuaIncompleteFact object represents the question that has been asked. It has at most one target element missing, which the Lua script must attempt to find the information for.

The LuaIncompleteFact object also includes:

an entity, which is the object of the question (unless the question target is the entity itself, in which case the entity value is empty).
zero or more LuaIncompleteFactProperty objects, which define a property of the question. Properties might be negated (that is, you want to find facts that do not match the property).

Each LuaIncompleteFactProperty object can also contain zero or more LuaIncompleteFactQualifier objects, which define a qualifier for the property. Qualifiers might be negated (that is, you want to find facts where the property does not match the qualifier).

You initialize the LuaCodifiedFact object from a LuaIncompleteFact object by using the initToCodifiedFact method. The LuaCodifiedFact object must not have any missing elements (for example, it must have an entity value).

The LuaCodifiedFact can also include zero or more LuaCodifiedFactProperty objects, which specify a property of the fact. Each LuaCodifiedFactProperty object can also have zero or more LuaCodifiedFactQualifier objects.

Entities, properties, and qualifiers are all coded on entry into the function, and decoded before Answer Server returns the information to the end user.

The Lua script has access to Lua functions and methods that are included in many Knowledge Discovery products, as well as functions and methods that are specific to Answer Server. For full details and examples of the available functions, refer to the Answer Server Reference.

Create Coding Files

The coding files are simple files that describe the entity, property, and qualifier codes in your Fact Bank system. It also defines any aliases for any of the entities, properties, and qualifiers, and maps all aliases to the same code.

A Fact Bank system requires four coding files:

code_to_property.txt. Assigns a unique code to each property and qualifier in your data, as well as a canonical human-readable name and the data type.
property_to_code.txt. An inverse mapping of the property and qualifier codes, including any aliases.
code_to_entity.txt. Assigns a unique code to each entity in your data (that is, things for which you might want to know the values of a property).
entity_to_code.txt. An inverse mapping of the entity codes, including any aliases.

The following sections use a simple example to show how to create the coding files from your data.

Example Data

The example data starts with facts, organized in a table. This version uses CSV format:

product_name, color, buy_price, sell_price, sold_last_year
alpha, red, 10, 12, 3500000
beta, blue, 11, 13, 2000000
gamma, green, 9, 10, 1000000

For this example, you might want to be able to answer questions such as:

What is the purchase price for alpha?
What was the selling price of beta?
What color is gamma?

Generate the Property Code Files

The properties in your data are the values that you want to find in the Fact Bank. For a table like the one in this example, the properties are the columns in the table.

The code_to_property.txt coding file assigns a unique code for each property and qualifier. This coding file also defines the canonical human-readable name for the property or qualifier, and sets its type. You can use the following types:

string. The property or qualifier values are strings.
time. The property or qualifier values are times in the ISO format YYYY-MM-DDTHH:NN:SS.
entity. The property or qualifier values are entity codes. In this case, you must list the entity code in the code_to_entity.txt file, and you must list the possible values for this entity in the entity_to_code.txt file. This option allows you to map multiple values to the same qualifier code.

NOTE: If your data values contain punctuation characters, such as commas (,) and equals signs (=), you must percent-encode the value in the coding files. For example, use %3D for an equals sign.

For example, the following sample is the code_to_property.txt file for the example data in the previous section.

PRODUCT_NAME=product,string
COLOR=color,string
BUY_PRICE=buying price,string
SELL_PRICE=selling price,string
SOLD_LAST_YEAR=sold last year,string

The property_to_code.txt coding file contains the inverse mapping of the code_to_property.txt file, without the type information. You can also include aliases for a value, on a separate line.

For example, the following sample is the property_to_code.txt file for the example data. It includes the alias sale price for the SELL_PRICE code.

product=PRODUCT_NAME
color=COLOR
buying price=BUY_PRICE
purchase price=BUY_PRICE
selling price=SELL_PRICE
sale price=SELL_PRICE
sold last year=SOLD_LAST_YEAR

Generate the Entity Code Files

The entities are the things that you want to find the property values for. For the example table, the obvious choice is the product_name.

The code_to_entity.txt coding file assigns a unique code to each entity.

For example, the following sample is the code_to_entity.txt for the example data.

ALPHA=alpha
BETA=beta
GAMMA=gamma

The entity_to_code.txt coding file contains the inverse mapping of the code_to_entity.txt. You can also include aliases for the entity names, on a separate line.

For example, the following sample is the entity_to_code.txt for the example data. It includes the alias alpha one for the ALPHA code.

alpha=ALPHA
beta=BETA
gamma=GAMMA
alpha one=ALPHA

Generate the Fact Store Data

This section describes how to convert a table of information into Fact Store content, for a SQL database backend type. It uses the example table specified in the Create Coding Files, and also assumes you have set the entity and property codes as described in that section.

product_name, color, buy_price, sell_price, sold_last_year
alpha, red, 10, 12, 3500000
beta, blue, 11, 13, 2000000
gamma, green, 9, 10, 1000000

Create a Fact Store Table for a SQL Database

In the SQL database backend, each property and property value for a particular entity is a row in the Facts table. For more information about the format of this table, see Set Up a SQL Backend as Fact Store.

The following table shows the table rows for the alpha product, assuming that all these properties refer to the same qualifier combination.

entity_code	property_code	property_value
`ALPHA`	`COLOR`	`red`
`ALPHA`	`BUY_PRICE`	`10`
`ALPHA`	`SELL_PRICE`	`12`
`ALPHA`	`SOLD_LAST_YEAR`	`35000000`

For this data, the qualifiers you use in the qualifiers table might include a year, or a selling region. For example:

qualifier_combination	qualifier_code	qualifier_value
0	`YEAR`	`2015`
0	`REGION`	`Americas`

Set up a SQL Database for Coding Information

The coding information in Fact Bank describes the entity, property, and qualifier codes in your Fact Bank system. It also defines any aliases for any of the entities, properties, and qualifiers, and maps all aliases to the same code.

You can store the coding information as a series of text files (see Create Coding Files), or in a SQL database.

You configure your Fact Bank to use a coding database by setting the CodifierType parameter in your Fact Bank system to odbc, and creating a configuration section for the coding database. For more information, see Configure the Fact Bank System.

Create a Codings SQL Database

Answer Server can connect to any RDBMS that supports SQL. The most fully tested options are:

SQLite
PostgreSQL (version 9.3 or later is required)

The SQL coding database has four required tables:

property_codes. Assigns a unique code to each property and qualifier in your data, as well as a canonical human-readable name and the data type.
properties. An inverse mapping of the property and qualifier codes, including any aliases.
entity_codes. Assigns a unique code to each entity in your data (that is, things for which you might want to know the values of a property).
entities. An inverse mapping of the entity codes, including any aliases.

Your Answer Server installation includes a PostgreSQL schema file for these tables, and a utility script that uses the psql utility to apply the schema to a database. These files are available in the /factbank/schemas/postgresql/codings directory in your installation.

The following sections describe these tables in more detail.

Property_Codes Table

The properties in your data are the values that you want to find in the Fact Bank. The property_codes table contains a unique code for each property and qualifier. This table also defines the canonical human-readable name for the property or qualifier, and sets its type.

Column	Type	Description
`id`	text	The ID for the property or qualifier.
`code`	text	The unique code for the property or qualifier.
`canonical_name`	text	The canonical name for the property (any aliases that you define in the `properties` table refer back to this name).
`type`	text	The type of the property. You can use the following types: * `string`. The property or qualifier values are strings. * `time`. The property or qualifier values are times in the ISO format `YYYY-MM-DDTHH:NN:SS`. * `item`. The property or qualifier values are entity codes. In this case, you must list the entity code in the `entity_codes` table, and you must list the possible values for this entity in the `entities` table. This option allows you to map multiple values to the same qualifier code.

Properties Table

The properties table contains the inverse mapping of the property_codes file, without the type information. You can also include aliases for a value, in a separate row.

Column	Type	Description
`id`	text	The ID for the property or qualifier value.
`name`	text	The name of the property or qualifier. This value can be an alias.
`code_id`	text	The ID of the row in the `property_codes` table that corresponds to this property or qualifier.

Entity_Codes Table

The entities are the things that you want to find the property values for. The entity_codes table assigns a unique code to each entity.

Column	Type	Description
`id`	text	The ID for the entity.
`code`	text	The unique code for the entity.
`canonical_name`	text	The primary name for the entity (any aliases that you define in the `entities` table refer back to this name).
`weight`	integer	The entity weight. If entities with similar names are returned as candidate answers, the entity with the higher weight scores more highly.

Entities Table

The entities table contains the inverse mapping of the entity_codes file. You can also include aliases for a value, in a separate row.

Column	Type	Description
`id`	text	The ID for the entity alias.
`name`	text	The name of the entity. This value can be an alias.
`code_id`	text	The ID of the row in the `entity_codes` table that corresponds to this entity.

Import Codings into a Database from Coding Files

The Answer Server installation includes a Python script utility, sql_import.py, to allow you to migrate from an existing set of coding files to a SQL codings database.

To run the script, you need:

an existing set of coding files
the details of an Content component that the script can connect to. The script uses this Content to generate stems of the canonical names that it inserts into the database. This Content must have the same stemming configuration as Fact Bank for the language that the codings apply to. Content must be running before you run the script.

To import your codings from an existing set of coding files, you run the script against the directory that contains the coding files, and provide the details of the Content component.

This script creates the required tables in your database, with the VARCHAR lengths correctly sized for your data. It also inserts the codings into the tables for the odbc fact codifier.

NOTE: The insertion is transactional. If the script is successful, it imports all the data. If there are any errors, the script does not import any data.

Manage the Codings Cache

Answer Server uses a cache of codings data to improve performance when it is retrieving the codings. As well as caching valid codings, it caches a 'not found' entry when it looks up an entity that does not exist, to prevent multiple unsuccessful lookups for the same thing.

By default, Answer Server removes old entries from the cache only when it runs out of allocated space. When you do not update the codings information very often, this option is fine. However, if you update the codings regularly and want Answer Server to pick up the changes in a timely manner, you might need to update the cache more frequently.

You can configure Answer Server to automatically remove old items from the cache when you use an ODBC codings database. You can also use a ManageResources action to manually reload the codings.

Expire Codings Cache Entries Automatically

You configure automatic codings cache expiration by using the CacheExpirationInterval and CacheNotFoundExpirationInterval parameters, which you set in the CodingsConfigSection (see Configure the Fact Bank System).

NOTE: You can use automatic codings expiration only when you use the ODBC codifier type (see Set up a SQL Database for Coding Information).

The CacheExpirationInterval parameter controls how long to keep entries for valid codings in the cache. The CacheNotFoundExpirationInterval parameter controls how long to keep entries for entities that were not found.

Depending on your use case, it is probably more common that you add new entries to the codings database rather than modifying the existing values. In this case, you might want to set CacheNotFoundExpirationInterval to be more frequent than CacheExpirationInterval.

For example:

[MyFactBank]
CodifierType=ODBC
CodingsConfigSection=MyCodifiers
...

[MyCodifierSection]
CacheExpirationInterval=86400
CacheNotFoundExpirationInterval=43200

For more information about these configuration parameters, refer to the Answer Server Reference.

Update the Codings Database Manually

You can reload the coding database manually by using the ManageResources action. This option updates the codings values for all codifier types:

When CodifierType is odbc, Answer Server removes all current cached coding lookups.
When CodifierType is files, Answer Server reloads the coding maps from disk to reflect any changes. It uses the raw text files if they are present, or the generated dat files otherwise.

For example:

Action=ManageResource&SystemName=FactBank
data={
   "operation":"reload",
   "type":"codifier"   
   }

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

The Question Parser Named Entity Recognition Grammar

The Fact Bank Question Parser is a Named Entity Recognition grammar designed for question answering, which the Answer Server internal Named Entity Recognition module uses to parse questions. This special grammar file defines many different forms that questions can take, and extracts the entities, properties, and qualifiers in the questions.

In general, an entity is the topic of the question, or a topic in your Fact Store data. Entities have properties, which define pieces of information that you might want to find, or which you might want to use to find a particular entity. A qualifier is a piece of information that modifies the property.

For example, in the question What is the population of the USA in 1850, you might define:

USA to be the entity.
population to be the property.
1850 to be a qualifier.

Many questions can be interpreted in more than one way, depending on how you set up your data.

The Fact Bank grammar can find the entities, properties, and qualifiers in a variety of different question formations.

When the Question Parser processes a question, the grammar might find several valid interpretations. In this case, the Question Parser returns all the options to Answer Server, which attempts to find the associated entities, properties, and qualifiers in your coding files, and then in your data.

The values that match in your Fact Store at this stage depend on how you have set up and stored your data.

NOTE: For time and entity type answers, Answer Server merges duplicate answers when multiple interpretations return the same value.

The examples in the sections below demonstrate many of the different forms of questions in English that the Question Parser can detect. The questions are examples, and the list is not exhaustive. In addition, some of the forms are not mutually exclusive (that is, Question Parser might detect both forms). In these cases, the correct form depends on your data.

Processors

The Q&A grammar also detects a number of processors, which affect the question in a similar way to qualifiers, but which might require further calculation on the data. The following processors are supported (processors listed on the same line are equivalent):

min, minimum
max, maximum
mean, average
total, sum
first, oldest
last, latest

Example Questions

The following section lists several example questions in forms that the Question Parser can parse, and which Answer Server can use to retrieve the relevant facts from the Fact Store.

In the questions, entities are specified in italics, properties are specified in bold, and qualifiers are underlined.

Questions to Find a Property Value

The following questions show forms where the Question Parser detects an entity and property name, and any associated qualifiers. For these questions, Answer Server attempts to find the property value in the Fact Store.

What is the population of France?
What is France's population?
Can you tell me the French population?
The population of France is what?
How many people live in France?

This question also matches the property number of people (the grammar automatically constructs this property because of the how many in the question).
What was the population of France in 2010?
What is the female population of France?
What is the non-female population of France?

In this example, the qualifier female is negated, so Answer Server finds facts that do not have this qualifier.
What is the population of France that is female?
What is the population of France that isn't female?

In this example, the qualifier female is negated, so Answer Server finds facts that do not have this qualifier.
What did Dickens write in 1837?
Who discovered America in 1492?

This question also matches the property discovered by (the grammar automatically constructs this property because of the who in the question).
What is the France population above 60000000?

Questions to Find Processed Property Value

The following questions show forms where the Question Parser detects an entity and property name, and a processor that qualifies the value that the question requests. For these questions, Answer Server attempts to find the property value in the Fact Store.

Processors are marked in monospace font.

What is the latest population of Russia?
What is the maximum male population of Russia?
When was George Washington first elected?
What are the total electoral votes of George Washington?

Questions to Find the Name of an Entity

The following questions show forms where the Question Parser detects a property and one or more property values. For these questions, Answer Server attempts to find the name of an entity in the Fact Store.

Property values are marked in bold italic.

Where is Paris the capital of?
Whose capital is Paris?
Which country has a capital that is Paris?
Who was president in 1810?
Who was president of America in 1810?
Who are the presidents of America who are fictional?

In this example, the fictional qualifier modifies the property presidents, which has the value America.
Who are the presidents of America who are male?

In this example, male is treated as the value of a separate unnamed property of the entity that the question requests.
What country borders France and Spain?
What country borders Portugal?
What products are there with interest rates above 0.3%?
What products are there with interest rates between 0.1 and 0.3%?

Questions to Find the Value of a Qualifier

The following questions show forms where the Question Parser detects an entity, a property, and a property value. For these questions, Answer Server attempts to find the value of a qualifier that matches these values.

When did the USA have George Washington as president?

This question matches a special point in time qualifier.
When did George Washington become president?

This question matches the special position held property, and a special start time qualifier.

Modify the Question Parser Grammar

The default question parser Named Entity Recognition grammar provides a large number of possible questions in English (see Example Questions). Versions of this grammar file are also available in French, German, Italian, Portuguese, and Spanish.

However, if you want to use a Fact Bank in a different language, or if you find that the results for a particular question that you want to use are not ideal, you can add your own entities to the Fact Bank User Grammar.

The QuestionUserGrammar.xml file is included in your Answer Server installation, with the other Fact Bank resources. To modify the Question Parser grammar, you must modify this XML file and compile it by using the edktool command-line tool, which is included in the Named Entity Recognition SDK.

The QuestionUserGrammar.xml has comments that explain in more detail how to modify the grammar. You can add new entities to the file, for example to provide question formats in different languages. It includes the content in the existing question_grammar_en.ecr file, so your modifications extend the existing grammar.

When you have modified the grammar, you compile it and deploy it in Answer Server, replacing the standard question_grammar_en.ecr file.

For more information about Named Entity Recognition grammars and edktool, refer to the Named Entity Recognition User and Programming Guide.

Configure Security in Fact Bank

You can use Knowledge Discovery mapped security with Fact Bank, by including the ACL information in your SQL backend fact store.

To use mapped security with Fact Bank you must:

configure the appropriate security types in your Answer Server configuration file.
uses a sources table in your SQL database fact store, with the ACL values.
add a security_types table in your SQL database fact store, with the details of the security types.

Configure the Security Types in Answer Server

Security configuration in Answer Server is similar to the configuration in the Content component. Depending on your data sources, it is likely that your Answer Server security configuration contains the same security types as your Content component data store.

You do not need any additional security libraries to run security in Answer Server fact bank.

To configure security in Answer Server

Open your configuration file in a text editor.
Find the [Security] configuration section, or add one if it does not exist.
In the [Security] section, set the SecurityInfoKeys parameter to specify the security encryption keys to use to encrypt and decrypt the security information. You can set the SecurityInfoKeys parameter either to the name of an AES key file (recommended) or to a comma-separated list of four signed 32-bit integers. For information about how to generate a key file with the autpassword command-line tool, refer to the Knowledge Discovery Administration Guide.

For example:
```
[Security]
SecurityInfoKeys=MyAESKeyFile.ky
```
In the [Security] section, list the security types that you want to use.
```
0=NT
1=Netware
2=Notes
3=Exchange
```
Create a section for each of the security types you defined (the section must have the same name as the security type). For each section, provide settings that determine how Answer Server handles that security type. For example:
```
[NT]
Type=AUTONOMY_SECURITY_V4_NT_MAPPED

[Netware]
Type=AUTONOMY_SECURITY_NETWARE_MAPPED

[Notes]
Type=AUTONOMY_SECURITY_V4_NOTES_MAPPED

[Exchange]
Type=AUTONOMY_SECURITY_EXCHANGE_MAPPED
```
Save and close the configuration file.

Set Up Fact Store Tables for Security

To use mapped security with your facts, you must use the sources table in your SQL fact store.

The sources table contains details of the source for your facts. Each source has an ID, which you use in the facts table to identify the source for an individual fact. For example:

Facts Table

entity_code	property_code	property_value	qualifier_combination	source_id
`COMPANY`	`CEO`	`Jane Smith`	0	1

Sources Table

id	source
1	`http//www.example.com/about`

When you use mapped security, the sources table also includes an access control list (ACL) for each source, and a security type ID. The security type ID corresponds to a row in the security_types table, which contains details of your configured security types.

For example:

Sources Table

id	source	acl	security_type_id
1	`http//www.example.com/about`	1:U:G:NU:9sjbyPA,9tnU38jBwfA:NG:9sjbxMHOwt/d8A	3

Security_Types Table

id	friendly_name
1	`Exchange`
2	`Netware`
3	`NT`

For more information about the tables in your SQL fact store, see Set Up a SQL Backend as Fact Store.

Set Up a Passage Extractor System

This section describes how to set up a Passage Extractor system, and configure the subcomponents.

Configure the Passage Extractor System

The Answer Server configuration file contains information about the subcomponents in your Passage Extractor systems.

For any Passage Extractor system, you must configure the host and port details of your data store, which is a Content component that contains the documents that Answer Server uses to find answers. For entity extraction, you must also configure the details for your Named Entity Recognition grammars, and the Passage Extractor Agentstore component.

Passage extractor also uses question classifiers, to determine the type of a question, and therefore what entities to extract from candidate answers. The classifier is required. The Answer Server installation includes classifiers for some languages, but for others you must train a classifier yourself.

The following procedure describes how to configure the Passage Extractor system in Answer Server.

For more details about the configuration parameters for the Passage Extractor system, see Passage Extractor System Configuration Parameters.

To configure the Passage Extractor System

Open the Answer Server configuration file in a text editor.
Find the [Systems] section, or create one if it does not exist. This section contains a list of systems, which refer to the associated configuration sections for each system.
After any existing systems, add an entry for your new Passage Extractor system. For example:
```
[Systems]
0=MyAnswerBank
1=MyFactBank
2=MyPassageExtractor
```
Create a configuration section for your Passage Extractor system, with the name that you specified. For example, [MyPassageExtractor``].
Set Type to PassageExtractor.
Set IDOLHost and IDOLACIPort to the host name and ACI Port of the Content component that contains the documents that you want to use to find answers.

NOTE: If you want to use synonyms to expand queries, set these parameters to the host and port of the Query Manipulation Server (QMS) that provides access to your synonyms. Set the host and port of the Content component in the QMS configuration file instead. For more information about how to enable synonyms, see Use Synonyms to Expand Queries.
Set AgentstoreHost and AgentstoreACIPort to the host name and ACI Port of the Content component that contains entity agents.
Set EductionGrammars to a comma-separated list of the Named Entity Recognition grammars to use for entity extraction.
Set the ClassifierFile parameter to the path of the question classifier file, and set LabelFile to the path of the label file.

TIP: The Answer Server installation includes classifier and labels files for English and German. For example, to use the default files for the English language, set ClassifierFile to the location of the svm_en.dat file, and set LabelFile to the location of the labels_en.dat file.

If you want to train your own classifier or are configuring a Passage Extractor system for use with another language, set the ClassifierFile and LabelFile parameters to the locations where you want Answer Server to save the question classifier and label files, when you perform training. For information about how to train classifiers, see Train Passage Extractor Classifiers.
Save and close the configuration file.
Restart Answer Server for your changes to take effect.

For example:

[MyPassageExtractor]
Type=PassageExtractor
// Data store Content
IdolHost=localhost
IdolAciport=6002
// Entity Agentstore
AgentStoreHost=localhost
AgentStoreAciport=5002
// Eduction
EductionGrammars=./resources/grammars/question_grammar_en.ecr,./passageextractor/grammars/number_en.ecr,./passageextractor/grammars/person_en.ecr,./passageextractor/grammars/date_en.ecr,./passageextractor/grammars/money_en.ecr
// Classifier Files
ClassifierFile=./passageextractor/classifiertraining/svm_en.dat
LabelFile=./passageextractor/classifiertraining/labels_en.dat
EntityExtractionFile=./passageextractor/configuration/entity_extraction_en.json
SurfacePatternsFile=./passageextractor/configuration/surface_patterns_en.json
ClassifierBehaviorFile=./passageextractor/configuration/classifier_behavior.json

Change the Passage Extractor Language

The default installation of passage extractor includes the question_grammar_en.ecr, and example question classifier training files for English. To use passage extractor in another language, you must:

create a new question classifier in the new language. See Train Passage Extractor Classifiers.
set the Language configuration parameter to the appropriate language, either in the [Server] section (to set the language for all of Answer Server), or in the passage extractor system configuration section (to set the language for just passage extractor). You might also want to set the StopList parameter. See Language Configuration.
set the EductionGrammars parameter to use the grammar file for the appropriate language. Passage extractor uses the same grammar files as fact bank. The Answer Server installation includes appropriate grammars for English, French, German, Italian, Portuguese, and Spanish. If you are interested in using passage extractor in other languages, contact your OpenText account manager.

Train Passage Extractor Classifiers

The Answer Server Passage Extractor uses a question classifier to determine what type a question is, and therefore what entities (if any) to extract from candidate answers. The type refers to the type of information that the question is requesting. For example, the question How many points make up a perfect fivepin bowling score? is looking for a number, while the question What is an annotated bibliography? is looking for a description.

The question classifier is always required. The Passage Extractor system does not return any answers without it.

The Answer Server installation includes classifiers for the English and German languages. For information about configuring which classifier to use, see Configure the Passage Extractor System. If the default classifier does not perform well for your use case, or you want to use Passage Extractor with other languages, you can train your own classifier.

The following sections provide more information about how to create and train your own classifiers.

Create a Training File

To train a question classifier, first create a training file to describe the kind of question classifications that you expect to send to your Passage Extractor. Each line of the training file defines a label and an example question, in the following format:

Label;Example Question

The example questions are the training. The label specifies the kind of information that the question is requesting. For example, the first few lines of the training file might be:

DESC:desc;What did the only repealed amendment to the U.S. Constitution deal with?
NUM:count;How many points make up a perfect fivepin bowling score?
DESC:def;What is an annotated bibliography?
NUM:date;What is the date of Boxing Day?

The default training file uses a Text Retrieval Conference (TREC) classification system to specify question classifiers. OpenText recommends that you use this classification system, which is based on a commonly used set. For more information, see Training File Labels. However, you can use your own classification system if required.

Train a Classifier

To train the question classifier, you use the ManageResources action, which accepts a JSON object with the details of the training file. For example:

action=ManageResources&SystemName=passageextractor&Data=JSON

Where the JSON object takes the following form:

{
   "operation": "train",
   "type": "classifier",
   "trainingfile": "classifier_training.txt",
   "savemodel": true
}

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

If you do not want to save the training model (for example, during testing), set savemodel to false.

NOTE: You can save classifiers (by setting savemodel to true) only if you set the ClassifierFile and LabelFile configuration parameters in your Passage Extractor system configuration. See Configure the Passage Extractor System.

The trainingfile parameter sets the location and name of a suitable training file. The training file contains a set of training questions, and a label that specifies the sort of answer that the question is looking for (for example, a person, place, or description).

You can use the GetResources action to retrieve the whole JSON schema for the operation, in the same way as for Answer Bank systems. See Find the JSON Schema for Your Update.

Classifier Behavior File

In addition to the main classifier and label files, there is a classifier behavior file, which is available in the Answer Server installation.

The classifier behavior file contains details of question classifications that it must treat differently. In particular, it includes information about whether to always or never consider other question classifications when a particular classification is identified as the primary classification.

For example, you generally want to consider other location classifications when a question matches the LOC:other classification. Similarly, for classifications that match descriptive questions you can explicitly never include other classifications, because classifications that match entities are less relevant, but might score higher in the results.

The primary classification is determined by a probability threshold, which is 0.85 by default.

If you move or rename the classification behavior JSON file, modify the ClassifierBehaviorFile configuration parameter to specify the new name and location.

Training File Labels

The label has two parts, separated by a colon. The first part is the class of the question, the second part is a subdivision. There are six classes:

Abbreviation (ABBR). Questions concerning abbreviations.
Entity (ENTY). Questions about entities (things).
Description (DESC). Questions that ask for a definition or a description.
Human (HUM). Questions about people or organizations.
Location (LOC). Questions about places.
Numeric (NUM). Questions about numbers.

The following table describes the available subdivisions for each class.

Label	Description	Example question
Abbreviation
`ABBR:abb`	Abbreviation questions.	What is the abbreviation for micro?
`ABBR:exp`	Expression questions.	What does HPE stand for?
Entity
`ENTY:animal`	Animal questions.	Which type of bird migrates between the North and South pole?
`ENTY:body`	Organs of the body.	Which artery takes blood to the head?
`ENTY:color`	Colors.	What was FDR's favorite color?
`ENTY:cremat`	Inventions, books, other creative pieces.	What film starred Al Pacino and Robert Deniro?
`ENTY:currency`	Currency names.	What currency do they use in Laos?
`ENTY:dismed`	Diseases and medicine.	What diseases can be transmitted by mosquitoes?
`ENTY:event`	Events.	What major sporting event was held in Australia in 2000?
`ENTY:food`	Food.	What Italian dish is made of soft dumplings?
`ENTY:instrument`	Musical instrument.	What is Jimi Hendrix famous for playing?
`ENTY:lang`	Languages.	What language is spoken in Cambodia?
`ENTY:letter`	Letters like a-z.	Which letter is the most common in Finnish?
`ENTY:other`	Other entities.	Which shape has 14 sides?
`ENTY:plant`	Plants.	What is the most poisonous plant?
`ENTY:product`	Products.	What shampoo is best for dandruff?
`ENTY:religion`	Religions.	What is the religion that worships Prince Phillip?
`ENTY:sport`	Sports.	Which sport involves people dressed in white standing around doing absolutely nothing for several days straight?
`ENTY:substance`	Elements and substance.	What chemicals make up mica?
`ENTY:symbol`	Symbols and signs.	What is the chemical formula for diamond?
`ENTY:techmeth`	Techniques and methods.	What methods are used to measure atmospheric pressure?
`ENTY:termeq`	Equivalent terms.	What is the name of the Thai alphabet?
`ENTY:vehicle`	Vehicles.	What is the largest plane ever made?
`ENTY:word`	Words with a special property.	What English words have Japanese origin?
Description
`DESC:def`	A definition of something.	What is dyslexia?
`DESC:desc`	A description of something.	What is the difference between a centipede and a millipede?
`DESC:manner`	A manner of action.	How do I apply for a driving license?
`DESC:reason`	Reasons.	What caused the American civil war?
`DESC:yesno`	"Yes" or "no" questions.	Is the River Nile in Egypt?
Human
`HUM:gr`	A group or organization of persons.	Which body elects the president?
`HUM:ind`	An individual.	Who wrote 'The unbearable lightness of being?'
`HUM:title`	The title of a person.	What is his position in the company?
`HUM:desc`	A description of a person.	Who is Serena Williams?
Location
`LOC:city`	Cities.	What is the capital of France?
`LOC:country`	Countries.	Which country is the best governed?
`LOC:mount`	Mountains.	What is the highest mountain in Vietnam?
`LOC:other`	Other locations.	What is the biggest lake in the world?
`LOC:state`	States.	Which state has the highest lowest point?
Numeric
`NUM:code`	Postal codes or other codes.	What is the White House's post code?
`NUM:count`	The number of something.	How many pillars of faith are there in Islam?
`NUM:date`	Dates.	When was the battle of Waterloo?
`NUM:dist`	Linear measures.	How long is the River Nile?
`NUM:money`	Prices.	How much is that doggie in the window?
`NUM:ord`	Ranks.	Which episode of the Star Wars saga has the cutest aliens?
`NUM:other`	Other numbers.	What is Stephen Hawking's IQ?
`NUM:period`	The duration of something.	How long since the last ice age?
`NUM:perc`	Fractions and percentages.	What proportion of the Earth is covered in water?
`NUM:speed`	Speeds.	How fast is the speed of light?
`NUM:temp`	Temperature.	What is the boiling point of nitrogen?
`NUM:volsize`	Size, area, and volume.	How big is the sea?
`NUM:weight`	Weight.	How much does the average human weigh?

Configure Candidate Retrieval for Passage Extractor

When you send an Ask action to your Passage Extractor or Passage Extractor LLM system, Answer Server performs the following steps:

Question Classification. Answer Server analyzes the input question to classify the key elements of the question.
Candidate Retrieval. Answer Server uses the information from the classified question to send a query to the Content component to retrieve documents that might contain an answer.
Answer Generation. Answer Server finds the likely answer from the candidate documents, and returns it.

For the candidate retrieval step, and for the answer generation step you can choose whether to use the standard Knowledge Discovery conceptual approach, or to use a third-party LLM approach.

To use an LLM approach for the answer generation step, you configure a Passage Extractor LLM system (see Configure the Passage Extractor LLM System). To use the Knowledge Discovery conceptual approach, you configure a standard Passage Extractor system (see Configure the Passage Extractor System).

To configure candidate retrieval, you can use different settings in your system, depending on the approach you want to use.

Knowledge Discovery Conceptual Candidate Retrieval

The default method of candidate retrieval uses Knowledge Discovery conceptual search to retrieve answers from your Content component index. You must use this option when you do not have vectors indexed in your Content component.

Conceptual candidate retrieval does not require any additional configuration, but you can add options to refine your results. For example, you can set ACIMaxResults to set a maximum number of results to retrieve, and you can set CandidateRetrievalDefaults to a configuration section that defines other parameters to use in the Content component query.

Knowledge Discovery Vector Search Candidate Retrieval

You can use Knowledge Discovery vector search when your Content component contains vectors in VectorType fields. For more information about the Content component vector search, refer to the Content component Help.

To configure Answer Server to send vector searches to Knowledge Discovery, you must do some additional configuration in your Passage Extractor system configuration:

Set AnswerCandidateEmbeddingsSettings to enable vector search. This parameter points to a configuration section where you define additional settings for the vector search.
Create a vector settings configuration section. This section must set VectorField to define the VectorType field to query in the Content component index, and settings for the model to use to generate embeddings for the query text that Answer Server creates from your questions.
Create an embedding generation configuration section. This section provides details of the embedding generation model that you want to use. You can download and use a third-party model from Hugging Face (see Choose an Embedding Model ), or you can use a Lua or Python script for embedding generation (see Create an Embedding Generation Lua Script and Create an Embedding Generation Python Script).

NOTE: When using vector search, you can still use the other candidate retrieval configuration parameters. For example, ACIMaxResults to set a maximum number of results to retrieve, and you can set CandidateRetrievalDefaults to a configuration section that defines other parameters to use in the Content component query.

Choose an Embedding Model

The sentence transformer models use vector models from Hugging Face. You can choose any sentence-transformer model.

OpenText recommends the sentence-transformers/sentence-t5-large model (see https://huggingface.co/sentence-transformers/sentence-t5-large).

Create an Embedding Generation Lua Script

You can create your own Lua script model, using any method that you choose to generate the embedding data. You can use the Lua model to interact or access third party API embedding generation, such as the Hugging Face Inference API, or Inference Endpoints service.

The script must define a function called generateembeddings. This function must accept a single parameter, which is a string representing the text to generate embeddings for.

The function must return a table of tables, where each inner table contains floating point numbers. Each inner table therefore corresponds to a vector for that text.

You can optionally include a second table of tables, which returns offsets for the embeddings in the format:

{{embedding_1_start_offset, embedding_1_end_offset}, {embedding_2_start_offset, embedding_2_end_offset}, {embedding_3_start_offset, embedding_3_end_offset}, ...},

NOTE: If you want to use offset information in the Content component (for indexing or querying), you must use UTF-8 byte offsets.

For example:

function generateembeddings(text)
   return {{1,2,3,4}, {5,6,7,8}, {9,10,11,12}}, {{34,48}, {48, 124}, {124, 156}}
end

In this example, the function returned three embeddings in the first table (with three nested tables). The second table is the offset values. The vector {1,2,3,4} starts at offset 34 and ends at 48. The second vector {5,6,7,8} starts at 48 and ends at 124, and so on.

Create an Embedding Generation Python Script

You can create your own Python script model, using any method that you choose to generate the embedding data. You can use the Python model to interact or access third party API embedding generation, such as the Hugging Face Inference API, or Inference Endpoints service.

The script must define a function called generate_embeddings. This function must accept a single parameter, which is a UTF-8 string that represents the text to generate embeddings for.

Your script must handle any chunking of the text to generate the embeddings.

The function must return

a list of lists of floats, which is the generated embeddings
a tuple that consists of:
- a list of lists of floats, which is the generated embeddings
- a list of lists of integers, which are the offset values for the text chunks that were used to create the embeddings
  
  NOTE: If you want to use offset information in the Content component (for indexing or querying), you must use UTF-8 byte offsets.

For example:

def generate_embeddings(input_text):
    return [[-0.1, 0.2, -0.3, 0.4, -0.5]]

TIP: You can provide a requirements.txt file for any third-party modules that you want to use, by setting the RequirementsFile parameter in your model configuration. See Configure Answer Server for Embedding Generation and Search.

Configure Answer Server for Embedding Generation and Search

You must configure your embedding generation in the Answer Server configuration file, with any suitable configuration section name. You then refer to this from your passage extractor system.

To configure Answer Server to generate embeddings and use vector search

Open your configuration file in a text editor.
Create a new configuration section for your embedding generation model, for example:
```
[EmbeddingsGenerator]
```
Set the Type parameter to the type of model you want to use. For example:
```
[EmbeddingsGenerator]
Type=Transformer
```
Set additional parameters for your model. The required parameters depend on the type of model:
- Transformer models require you to set ModelName. You can set AccessToken to use a private model. You can optionally also set CacheDirectory, DataLimit, Device, EmbeddingPrecision, ModelMaxSequenceLength, ModelMinimumFinalSequenceLength, ModelRevision, ModelSequenceOverlap, NumProcessors, and OfflineMode.
- Lua models require you to set Script. You can also optionally set EmbeddingPrecision.
- Python models require you to set Script. You can also optionally set EmbeddingPrecision.
Find the Passage Extractor or Passage Extractor LLM system that you want to configure to use vector search.
Set the AnswerCandidateEmbeddingsSettings configuration parameter to the name of a configuration section where you define vector search settings. For example:
```
AnswerCandidateEmbeddingsSettings=VectorSettings
```
Create a new configuration section with the name you set.
In this new section, set EmbeddingsConfig to the name of your embeddings generator configuration section. Set VectorField to the name of the Content component VectorType field that contains the vector values that you want to search. For example:
```
[VectorSettings]
EmbeddingsConfig=EmbeddingsGenerator
VectorField=VECTORA
```
Save and close the configuration file.

For example:

[PassageExtractorSystem]
IDOLHost=localhost
IDOLACIPort=6002
Type=PassageExtractor
...
AnswerCandidateEmbeddingsSettings=VectorSettings

[VectorSettings]
EmbeddingsConfig=EmbeddingsGenerator
VectorField=VECTORA

[EmbeddingsGenerator]
Type=Transformer
ModelName=sentence-transformers/sentence-t5-large
ModelMaxSequenceLength=128

Entity Extraction in Passage Extractor

Passage Extractor uses entity extraction to provide more concise, specific answers. It attempts to find the shortest possible section of a document that answers the original question. Depending on the question, the answer might be a single word or name, or a few sentences of description.

There are two types of entity extraction that you can use:

Named Entity Recognition. Named Entity Recognition provides a set of grammars, which define the entities that you want to find. This method is very powerful for pattern matching, and finding entities that match a particular structure, such as phone numbers. Answer Server includes an embedded Named Entity Recognition module for entity extraction.
Agent matching. The Passage Extractor Agentstore component stores agents that define entities in the Agentstore component. Passage Extractor sends any candidate answers in an agent query, which returns the matching entity agents. This method is very powerful for entities that have a clearly defined value, such as names.

To get the most out of Passage Extractor, you must configure at least one of a Named Entity Recognition grammar or Agentstore component for entity extraction. You can use both to make the most out of the different methods, and to get the best answers.

Configure the Passage Extractor Agentstore

The Agentstore component is a specially configured Content component.

In agent search, you send plain text or a document to the Agentstore, which returns any agents that match the document. In Passage Extractor, you store entity agents in the Agentstore . For example, each entity agent might define a single name (perhaps with one or more alias names).

When you ask a question, Passage Extractor finds candidate answers in your data store, and uses an agent search to find the entities that these candidate answers contain.

Configure the Agentstore Component

The Answer Server package includes a predefined Passage Extractor Agentstore configuration file, as well as several predefined IDX documents that you can optionally use to populate your Agentstore with entities.

NOTE: You must use a separate Agentstore component for Passage Extractor and Answer Bank systems.

To configure the Agentstore component for your Passage Extractor

In your Answer Server installation directory, copy the Agentstore agentstore.cfg configuration file, and the IDX files.
Open your Agentstore installation directory.
Paste the Answer Server Agentstore configuration file and IDX files. Overwrite the installed configuration file (you might want to make a copy of it first).
Open the configuration file in a text editor.
Update the [License] section with the host and port information for your License Server. For more information, see Configure the License Server Host and Port.
In the [Server] section, find the Port parameter. Check that the specified port is available on the host machine, or change it to an available port.

NOTE: If you modify the port, make sure to update the system configuration in your Answer Server configuration file. See Configure the Passage Extractor System.
In the [Service] section, find the ServicePort parameter. Check that the specified port is available on the host machine, or change it to an available port.
Save and close the configuration file.

Index Entity Agents

After you have configured the Agentstore, you must index the entity agents that Passage Extractor uses.

To do this, you can use a DREADD index action to add the IDX files that you copied into the Agentstore installation directory. For example:

http://localhost:5001/DREADD?C:\AnswerServer\passageextractor\agents-HUM_ind.idx.gz

Customize Entity Extraction

The Passage Extractor entity extraction file provides Answer Server with a map to specify what components to use to extract entities, depending on the question classification.

When you ask a question, Passage Extractor classifies it by using the question classifier, and then finds matching documents and document sections in the data store. It uses Content component highlighting to find the most relevant passages, which it uses as candidate answers. Passage Extractor then uses Named Entity Recognition and an Agentstore component to find entities in the candidate answers that match the question classification.

For example, if you have an Agent entity database with the names of plants, and you send a question that Passage Extractor classifies as plants, Passage Extractor uses the Agentstore component to find the relevant plant entities in the candidate answer text.

By default, if you configure an Agentstore component, Passage Extractor uses the Agentstore for the classifications HUM:gr, all LOC classifications, ENTY:plant, ENTY:animal, and ENTY:lang. It uses Named Entity Recognition and Agentstore for the HUM:ind question classification, and Named Entity Recognition only for all other question classifications.

You can use the Entity Extraction file to modify these classifications, for example if you create additional Agent entity files for your data.

NOTE: You do not need to specify an entity type to extract for every question classification. If a question classification does not appear in the entity extraction file, Passage Extractor does not attempt to extract entities. This might be appropriate for many question classifications (for example, if the appropriate answer is a long description, there might not be a corresponding entity).

Passage Extractor also attempts to corroborate the candidate answers, by comparing how often particular entities occur. In most cases, this improves the quality of the result answers.

In some cases, corroboration might not be appropriate. For example, if valid answers include very common words (such as one and two), the words might occur in multiple places, and be falsely corroborated as a likely answer. For this reason, corroboration is turned off for the NUM:count entity type in the default entity extraction JSON file.

You might also want to turn corroboration off if likely answers occur only once in your data set. In these cases you can modify the entity extraction JSON file to turn corroboration off for particular entities.

The Entity Extraction File Format

The entity extraction file contains the question classifications, which match the values that you use in the classifier training file. For each question classification, it also contains at least one of:

a list of Named Entity Recognition entities that Passage Extractor must use to find entities for the question classification.
a list of Agentstore databases that Passage Extractor must query to find entities for the question classification.

When there is an Agentstore database, you can also specify Agent FieldText to use in a query to the Agentstore entity database for the question classification.

The entity extraction file is a JSON file, with the following structure:

{
   "entity_map": [
      {
         "entity_type": "QuestionClass1", 
         "agentstore": {
            "databases": [ListOfAgentstoreDatabases],
            "fieldtext": "FieldTextRestriction"
         }, 
         "eduction": {"entities": [ListOfEductionEntities]},
         "corroborate": Boolean
      },
      {
         "entity_type": "QuestionClass2", 
         "agentstore": {
            "databases": [ListOfAgentstoreDatabases],
            "fieldtext": "FieldTextRestriction"
         }, 
         "eduction": {"entities": [ListOfEductionEntities]},
         "corroborate": Boolean
      }
      ...
   ]
}

where,


`QuestionClassN`	is the name of the question classification (for example, `HUM:ind`).
`ListofEductionEntities`	is an array of relevant Named Entity Recognition entities.
`ListOfAgentstoreDatabases`	is an array of databases in the Agentstore component that contain relevant entities.
`FieldTextRestriction`	is a Content component `FieldText` expression to use to restrict the Agent query in the specified database.

You must specify at least one of the eduction or agentstore properties for each question classification. If you specify the agentstore property, the database property is required, but fieldtext is not.

If you do not want to use entity extraction for a particular question classification, do not include it in the entity extraction file.

The corroborate property is optional. The default value is true.

The following example gives some of the question classifications in the default entity extraction file:

{
   "entity_map": [
      {
         "entity_type": "HUM:ind", 
         "agentstore": {"databases": ["people"]}, 
         "eduction": {"entities": ["hum/ind"]}
      },
      {
         "entity_type": "NUM:date", 
         "eduction": {"entities": ["num/date", "date/*"]}
      },
      {
         "entity_type": "ENTY:plant", 
         "agentstore": {
            "databases": ["organisms"], 
            "fieldtext": "MATCH{PLANTAE,VIRIDIPLANTAE}:ORGANISMS_KINGDOM"
         }
      },
      {
         "entity_type": "NUM:count", 
         "eduction": {"entities": ["num/count"]}, 
         "corroborate": false
      },

...

Modify the Entity Extraction File

The default entity extraction file, included in your Answer Server installation , is appropriate for most installation. However, you might need to modify the file if:

you do not want to configure an Agentstore component for entity extraction, and want to use Named Entity Recognition entity extraction for those question classifications instead.
you create additional Agent entity files and index them into your Passage Extractor Agentstore.
you create custom Named Entity Recognition entities that you want to use for entity extraction.
you want to define entity extraction for additional question classifications
you want to turn off corroboration for some question classifications.

To update the entity extraction file

Open the entity extraction JSON file in a text editor.
Make the necessary modifications. You can add, delete, or update, any of details for the question classifications.

To turn off corroboration, add the corroborate property in a particular group and set it to false. For example:
```
{
   "entity_type": "NUM:count", 
   "eduction": {"entities": ["num/count"]}, 
   "corroborate": false
}
```
Save and close the entity extraction file.
Restart Answer Server for your changes to take effect.

NOTE: If you add new question classifications that do not exist in the classifier training file, you must also update the classifier training file and retrain the classifier. See Train Passage Extractor Classifiers.

Use a Different Entity Extraction File

You can use the EntityExtractionFile configuration parameter to configure the location of the entity extraction file. If you want to move or rename the entity extraction file, or use a different file for any reason, you must modify the value of this parameter to specify the name and location of the new file.

Troubleshoot Passage Extractor

This section contains some information about how to check that Passage Extractor is working correctly.

Passage Extractor Does Not Return Any Answers

Check that you have a question classifier trained and configured. Answer Server writes an error to the application log if there is no available classifier. See Train Passage Extractor Classifiers.
Check that the host and port details for the subcomponents are correct. In particular, check that the Content component that you use for the data store is configured correctly. See Configure the Passage Extractor System.

Passage Extractor Returns an Answer that is Incorrect or Unusual

Increase the log level for your Answer Server to FULL, by modifying the log stream configuration. See Customize Logging.

When the log level is set to FULL, Answer Server generates a lot of extra information about how Passage Extractor found its answers, including the candidate passages, extracted entities, and scoring information.

To improve answers in these cases, you might need to add additional entities, or rephrase the question. You might also want to check the data in your Content component data store, to see whether your data set contains appropriate content for the answer.

Set Up a Passage Extractor LLM System

This section describes how to set up a Passage Extractor LLM system, and configure the subcomponents.

Configure the Passage Extractor LLM System

The Answer Server configuration file contains information about the subcomponents in your Passage Extractor LLM systems.

For any Passage Extractor LLM system, you must configure the host and port details of your data store, which is a Content component that contains the documents that Answer Server uses to find answers. You must also configure the LLM module to use to generate or extract answers.

Passage extractor LLM also uses question classifiers, to determine the type of a question. The classifier is required. The Answer Server installation includes classifiers for some languages, but for others you must train a classifier yourself.

The following procedure describes how to configure the Passage Extractor LLM system in Answer Server.

For more details about the configuration parameters for the Passage Extractor LLM system, see Passage Extractor LLM System Configuration Parameters.

To configure the Passage Extractor System

Open the Answer Server configuration file in a text editor.
Find the [Systems] section, or create one if it does not exist. This section contains a list of systems, which refer to the associated configuration sections for each system.
After any existing systems, add an entry for your new Passage Extractor system. For example:
```
[Systems]
0=MyAnswerBank
1=MyFactBank
2=MyPassageExtractor
3=MyPassageExtractorLLM
```
Create a configuration section for your Passage Extractor LLM system, with the name that you specified. For example, [MyPassageExtractor``LLM``].
Set Type to PassageExtractorLLM.
Set IDOLHost and IDOLACIPort to the host name and ACI Port of the Content component that contains the documents that you want to use to find answers.

NOTE: If you want to use synonyms to expand queries, set these parameters to the host and port of the Query Manipulation Server (QMS) that provides access to your synonyms. Set the host and port of the Content component in the QMS configuration file instead. For more information about how to enable synonyms, see Use Synonyms to Expand Queries.
Set ModuleID to the name of the configuration section that provides details of the LLM module to use. For information about how to configure this, see Configure the LLM Module.
Set the ClassifierFile parameter to the path of the question classifier file, and set LabelFile to the path of the label file.

TIP: The Answer Server installation includes classifier and labels files for English and German. For example, to use the default files for the English language, set ClassifierFile to the location of the svm_en.dat file, and set LabelFile to the location of the labels_en.dat file.

If you want to train your own classifier or are configuring a Passage Extractor system for use with another language, set the ClassifierFile and LabelFile parameters to the locations where you want Answer Server to save the question classifier and label files, when you perform training. For information about how to train classifiers, see Train Passage Extractor Classifiers.
Save and close the configuration file.
Restart Answer Server for your changes to take effect.

For example:

[MyPassageExtractor]
Type=PassageExtractorLLM
// Data store Content
IdolHost=localhost
IdolAciport=6002
// Classifier Files
ClassifierFile=./passageextractor/classifiertraining/svm_en.dat
LabelFile=./passageextractor/classifiertraining/labels_en.dat

// Module to use
ModuleID=LLMExtractiveQuestionAnswering

[LLMExtractiveQuestionAnswering]
Type=ExtractiveQuestionAnsweringLLM
ModelName=distilbert/distilbert-base-uncased

Change the Passage Extractor Language

The default installation of passage extractor includes example question classifier training files for English. To use passage extractor in another language, you must:

create a new question classifier in the new language. See Train Passage Extractor Classifiers.
set the Language configuration parameter to the appropriate language, either in the [Server] section (to set the language for all of Answer Server), or in the passage extractor LLM system configuration section (to set the language for just passage extractor). You might also want to set the StopList parameter. See Language Configuration.

Configure the LLM Module

For a passage extractor LLM system, you must have an LLM module that defines the model that Answer Server must use. You can use the following types of models:

Extractive or Generative LLM. These options use a publicly available model from Hugging Face. See Choose a Question Answering Model.
Extractive or Generative Lua Script. These options use a Lua script to produce answers. For example, you might want to use your Lua script to generate answers using an HTTP endpoint. For these modules, Answer Server calls the Lua script and processes the response to use as the answers to a question. See Create a Question Answering Lua Script.
Generative Python Script. This option uses a Python script to produce answers. For example, you might want to use your Python script to generate answers using an HTTP endpoint. For this module, Answer Server calls the Python script and processes the response to use as the answers to a question. See Create a Question Answering Python Script.

The extractive question answering types find the answers in your documents and return the exact text as it occurs in the original text. The generative models can generate new text to answer the question, based on the information that it finds in your documents.

IMPORTANT: The emb subdirectory in the server package zip contains libraries and data required for embedded Python functionality. On Microsoft Windows platforms, you must add this directory to the system PATH variable to use extractive or generative LLM systems with an extractive or generative LLM, or a generative Python script.

Choose a Question Answering Model

The extractive and generative models use LLMs from Hugging Face. The types of models that you can use depend on the question answering method.

TIP: To find the type of a particular model, check the value of model_type in the config.json file on the web page for the model on Hugging Face.

For Extractive Question Answering, you can use any model with a model_type of question-answering, except for layoutlmv2, roformer, and lxmert.
For Generative Question Answering, you can use any model with a model_type of text2text-generation, except for encoder-decoder.

NOTE: The first time you use a particular model, Answer Server downloads and caches it (for example, when you first send a question to the passage extractor LLM system).

If Answer Server does not have an internet connection, you can use these question answering systems only if you have an existing cached model.

Create a Question Answering Lua Script

You can configure a Lua script to perform generative or extractive question answering. For example, you might want to use your Lua script to generate answers using an HTTP endpoint.

For extractive question answering, your script must define a function called perform_extractive_qa, which must accept two parameters:

the first parameter is a string that represents the question.
the second parameter is a string that defines the context from which the answer must be extracted.

The function must return a string that represents the answer to the question that has been extracted from the context. It can optionally also return a float between 0 and 1 corresponding to a score for the answer.

For example:

function perform_extractive_qa(question, context)
   return context, 0.95
end

For generative question answering, your script must define a function called perform_generative_qa, which must accept two parameters:

the first parameter is a string that represents the question.
the second parameter is a string that defines the context to base the answer on.

The function must return a string that represents the answer to the question, based on the provided context.

For example:

function perform_generative_qa(question, context)
   return string.format("Here is your answer: %s", string.sub(context, 1, 100))
end

Create a Question Answering Python Script

You can configure a Python script to perform generative question answering. For example, you might want to use your Python script to generate answers by using an HTTP endpoint.

For generative question answering, your script must define a function called perform_generative_qa, which must accept two parameters:

the first parameter is a string that represents the question.
the second parameter is a string that defines the context to base the answer on.

The function must return a string that represents the answer to the question, based on the provided context.

For example:

def perform_generative_qa(question: str, context: str) -> str:
   '''
   Sample generative question answering function.
   '''
   return f'Here is your answer: {context[:100]}'

TIP: You can provide a requirements.txt file for any third-party modules that you want to use, by setting the RequirementsFile parameter in your model configuration. See Configure the LLM Module.

Configure the LLM Module

After you create your model files, or your Lua or Python script, you must configure an LLM module section in your configuration file, which you refer to in your Passage Extractor LLM system configuration.

To configure the LLM Module

Open the Answer Server configuration file in a text editor.
Create a new configuration section for your LLM module. This is the configuration section name that you use in the ModuleID parameter when you configure the passage extractor LLM system. For example [LLMExtractiveQA]
In the new configuration section, set the Type parameter to one of the following values:
- ExtractiveQuestionAnsweringLLM. Use an extractive LLM to extract answers from Knowledge Discovery documents.
- GenerativeLLM. Use a generative LLM to generate answers based on information in your Knowledge Discovery documents.
- ExtractiveQuestionAnsweringLua. Use a Lua script to extract answers from Knowledge Discovery documents.
- GenerativeLua. Use a Lua script to generate answers based on information in your Knowledge Discovery documents.
- GenerativePython. Use a Python script to generate answers based on information in your Knowledge Discovery documents.
Set the required parameters for your module type:
- For a module that uses an LLM (that is, when Type is set to ExtractiveQuestionAnsweringLLM or GenerativeLLM), set ModelName to the model that you want to use. You can set AccessToken to use a private model. You can optionally set CacheDirectory, Device, ModelRevision, NumProcessors, and OfflineMode. For GenerativeLLM, you can also set ChunkSize and GreedySearch.
- For a module that uses a Lua script (that is, when Type is set to ExtractiveQuestionAnsweringLua or GenerativeLua), set Script to the path and file name for your Lua script.
- For a module that uses a Python script (that is when Type is set to GenerativePython), set Script to the path and file name for your Python script. You can optionally set RequirementsFile to define modules that your script uses.
For example:
```
[LLMExtractiveQuestionAnswering-Small]
Type=ExtractiveQuestionAnsweringLLM
ModelName=distilbert/distilbert-base-uncased

[LLMGenerativeQuestionAnswering-Large]
Type=GenerativeLLM
ModelName=google/flan-t5-base

[ExtractiveQuestionAnsweringLuaScript]
Type=ExtractiveQuestionAnsweringLua
Script=LLMscripts/extractive_script.lua

[GenerativeQuestionAnsweringLuaScript]
Type=GenerativeLua
Script=LLMscripts/generative_script.lua

[GenerativeQuestionAnsweringPythonScript]
Type=GenerativePython
Script=LLMscripts/generative_script.py
```
Save and close the configuration file.

Train Passage Extractor Classifiers

The question classifier is always required. The Passage Extractor system does not return any answers without it.

The following sections provide more information about how to create and train your own classifiers.

Create a Training File

Label;Example Question

The example questions are the training. The label specifies the kind of information that the question is requesting. For example, the first few lines of the training file might be:

DESC:desc;What did the only repealed amendment to the U.S. Constitution deal with?
NUM:count;How many points make up a perfect fivepin bowling score?
DESC:def;What is an annotated bibliography?
NUM:date;What is the date of Boxing Day?

Train a Classifier

To train the question classifier, you use the ManageResources action, which accepts a JSON object with the details of the training file. For example:

action=ManageResources&SystemName=passageextractor&Data=JSON

Where the JSON object takes the following form:

{
   "operation": "train",
   "type": "classifier",
   "trainingfile": "classifier_training.txt",
   "savemodel": true
}

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

If you do not want to save the training model (for example, during testing), set savemodel to false.

You can use the GetResources action to retrieve the whole JSON schema for the operation, in the same way as for Answer Bank systems. See Find the JSON Schema for Your Update.

Classifier Behavior File

In addition to the main classifier and label files, there is a classifier behavior file, which is available in the Answer Server installation.

The primary classification is determined by a probability threshold, which is 0.85 by default.

If you move or rename the classification behavior JSON file, modify the ClassifierBehaviorFile configuration parameter to specify the new name and location.

Training File Labels

The label has two parts, separated by a colon. The first part is the class of the question, the second part is a subdivision. There are six classes:

Abbreviation (ABBR). Questions concerning abbreviations.
Entity (ENTY). Questions about entities (things).
Description (DESC). Questions that ask for a definition or a description.
Human (HUM). Questions about people or organizations.
Location (LOC). Questions about places.
Numeric (NUM). Questions about numbers.

The following table describes the available subdivisions for each class.

Label	Description	Example question
Abbreviation
`ABBR:abb`	Abbreviation questions.	What is the abbreviation for micro?
`ABBR:exp`	Expression questions.	What does HPE stand for?
Entity
`ENTY:animal`	Animal questions.	Which type of bird migrates between the North and South pole?
`ENTY:body`	Organs of the body.	Which artery takes blood to the head?
`ENTY:color`	Colors.	What was FDR's favorite color?
`ENTY:cremat`	Inventions, books, other creative pieces.	What film starred Al Pacino and Robert Deniro?
`ENTY:currency`	Currency names.	What currency do they use in Laos?
`ENTY:dismed`	Diseases and medicine.	What diseases can be transmitted by mosquitoes?
`ENTY:event`	Events.	What major sporting event was held in Australia in 2000?
`ENTY:food`	Food.	What Italian dish is made of soft dumplings?
`ENTY:instrument`	Musical instrument.	What is Jimi Hendrix famous for playing?
`ENTY:lang`	Languages.	What language is spoken in Cambodia?
`ENTY:letter`	Letters like a-z.	Which letter is the most common in Finnish?
`ENTY:other`	Other entities.	Which shape has 14 sides?
`ENTY:plant`	Plants.	What is the most poisonous plant?
`ENTY:product`	Products.	What shampoo is best for dandruff?
`ENTY:religion`	Religions.	What is the religion that worships Prince Phillip?
`ENTY:sport`	Sports.	Which sport involves people dressed in white standing around doing absolutely nothing for several days straight?
`ENTY:substance`	Elements and substance.	What chemicals make up mica?
`ENTY:symbol`	Symbols and signs.	What is the chemical formula for diamond?
`ENTY:techmeth`	Techniques and methods.	What methods are used to measure atmospheric pressure?
`ENTY:termeq`	Equivalent terms.	What is the name of the Thai alphabet?
`ENTY:vehicle`	Vehicles.	What is the largest plane ever made?
`ENTY:word`	Words with a special property.	What English words have Japanese origin?
Description
`DESC:def`	A definition of something.	What is dyslexia?
`DESC:desc`	A description of something.	What is the difference between a centipede and a millipede?
`DESC:manner`	A manner of action.	How do I apply for a driving license?
`DESC:reason`	Reasons.	What caused the American civil war?
`DESC:yesno`	"Yes" or "no" questions.	Is the River Nile in Egypt?
Human
`HUM:gr`	A group or organization of persons.	Which body elects the president?
`HUM:ind`	An individual.	Who wrote 'The unbearable lightness of being?'
`HUM:title`	The title of a person.	What is his position in the company?
`HUM:desc`	A description of a person.	Who is Serena Williams?
Location
`LOC:city`	Cities.	What is the capital of France?
`LOC:country`	Countries.	Which country is the best governed?
`LOC:mount`	Mountains.	What is the highest mountain in Vietnam?
`LOC:other`	Other locations.	What is the biggest lake in the world?
`LOC:state`	States.	Which state has the highest lowest point?
Numeric
`NUM:code`	Postal codes or other codes.	What is the White House's post code?
`NUM:count`	The number of something.	How many pillars of faith are there in Islam?
`NUM:date`	Dates.	When was the battle of Waterloo?
`NUM:dist`	Linear measures.	How long is the River Nile?
`NUM:money`	Prices.	How much is that doggie in the window?
`NUM:ord`	Ranks.	Which episode of the Star Wars saga has the cutest aliens?
`NUM:other`	Other numbers.	What is Stephen Hawking's IQ?
`NUM:period`	The duration of something.	How long since the last ice age?
`NUM:perc`	Fractions and percentages.	What proportion of the Earth is covered in water?
`NUM:speed`	Speeds.	How fast is the speed of light?
`NUM:temp`	Temperature.	What is the boiling point of nitrogen?
`NUM:volsize`	Size, area, and volume.	How big is the sea?
`NUM:weight`	Weight.	How much does the average human weigh?

Configure Candidate Retrieval for Passage Extractor

When you send an Ask action to your Passage Extractor or Passage Extractor LLM system, Answer Server performs the following steps:

Question Classification. Answer Server analyzes the input question to classify the key elements of the question.
Candidate Retrieval. Answer Server uses the information from the classified question to send a query to the Content component to retrieve documents that might contain an answer.
Answer Generation. Answer Server finds the likely answer from the candidate documents, and returns it.

For the candidate retrieval step, and for the answer generation step you can choose whether to use the standard Knowledge Discovery conceptual approach, or to use a third-party LLM approach.

To configure candidate retrieval, you can use different settings in your system, depending on the approach you want to use.

Knowledge Discovery Conceptual Candidate Retrieval

Knowledge Discovery Vector Search Candidate Retrieval

To configure Answer Server to send vector searches to Knowledge Discovery, you must do some additional configuration in your Passage Extractor system configuration:

Set AnswerCandidateEmbeddingsSettings to enable vector search. This parameter points to a configuration section where you define additional settings for the vector search.
Create a vector settings configuration section. This section must set VectorField to define the VectorType field to query in the Content component index, and settings for the model to use to generate embeddings for the query text that Answer Server creates from your questions.
Create an embedding generation configuration section. This section provides details of the embedding generation model that you want to use. You can download and use a third-party model from Hugging Face (see Choose an Embedding Model ), or you can use a Lua or Python script for embedding generation (see Create an Embedding Generation Lua Script and Create an Embedding Generation Python Script).

Choose an Embedding Model

The sentence transformer models use vector models from Hugging Face. You can choose any sentence-transformer model.

OpenText recommends the sentence-transformers/sentence-t5-large model (see https://huggingface.co/sentence-transformers/sentence-t5-large).

Create an Embedding Generation Lua Script

The script must define a function called generateembeddings. This function must accept a single parameter, which is a string representing the text to generate embeddings for.

The function must return a table of tables, where each inner table contains floating point numbers. Each inner table therefore corresponds to a vector for that text.

You can optionally include a second table of tables, which returns offsets for the embeddings in the format:

{{embedding_1_start_offset, embedding_1_end_offset}, {embedding_2_start_offset, embedding_2_end_offset}, {embedding_3_start_offset, embedding_3_end_offset}, ...},

NOTE: If you want to use offset information in the Content component (for indexing or querying), you must use UTF-8 byte offsets.

For example:

function generateembeddings(text)
   return {{1,2,3,4}, {5,6,7,8}, {9,10,11,12}}, {{34,48}, {48, 124}, {124, 156}}
end

Create an Embedding Generation Python Script

The script must define a function called generate_embeddings. This function must accept a single parameter, which is a UTF-8 string that represents the text to generate embeddings for.

Your script must handle any chunking of the text to generate the embeddings.

The function must return

a list of lists of floats, which is the generated embeddings
a tuple that consists of:
- a list of lists of floats, which is the generated embeddings
- a list of lists of integers, which are the offset values for the text chunks that were used to create the embeddings
  
  NOTE: If you want to use offset information in the Content component (for indexing or querying), you must use UTF-8 byte offsets.

For example:

def generate_embeddings(input_text):
    return [[-0.1, 0.2, -0.3, 0.4, -0.5]]

Configure Answer Server for Embedding Generation and Search

You must configure your embedding generation in the Answer Server configuration file, with any suitable configuration section name. You then refer to this from your passage extractor system.

To configure Answer Server to generate embeddings and use vector search

Open your configuration file in a text editor.
Create a new configuration section for your embedding generation model, for example:
```
[EmbeddingsGenerator]
```
Set the Type parameter to the type of model you want to use. For example:
```
[EmbeddingsGenerator]
Type=Transformer
```
Set additional parameters for your model. The required parameters depend on the type of model:
- Transformer models require you to set ModelName. You can set AccessToken to use a private model. You can optionally also set CacheDirectory, DataLimit, Device, EmbeddingPrecision, ModelMaxSequenceLength, ModelMinimumFinalSequenceLength, ModelRevision, ModelSequenceOverlap, NumProcessors, and OfflineMode.
- Lua models require you to set Script. You can also optionally set EmbeddingPrecision.
- Python models require you to set Script. You can also optionally set EmbeddingPrecision.
Find the Passage Extractor or Passage Extractor LLM system that you want to configure to use vector search.
Set the AnswerCandidateEmbeddingsSettings configuration parameter to the name of a configuration section where you define vector search settings. For example:
```
AnswerCandidateEmbeddingsSettings=VectorSettings
```
Create a new configuration section with the name you set.
In this new section, set EmbeddingsConfig to the name of your embeddings generator configuration section. Set VectorField to the name of the Content component VectorType field that contains the vector values that you want to search. For example:
```
[VectorSettings]
EmbeddingsConfig=EmbeddingsGenerator
VectorField=VECTORA
```
Save and close the configuration file.

For example:

[PassageExtractorSystem]
IDOLHost=localhost
IDOLACIPort=6002
Type=PassageExtractor
...
AnswerCandidateEmbeddingsSettings=VectorSettings

[VectorSettings]
EmbeddingsConfig=EmbeddingsGenerator
VectorField=VECTORA

[EmbeddingsGenerator]
Type=Transformer
ModelName=sentence-transformers/sentence-t5-large
ModelMaxSequenceLength=128

Passage Extractor LLM Answers

When you send an Ask action for your Passage Extractor LLM system, Answer Server includes some additional highlighting to allow you to verify your answers. The highlighting is particularly useful for generative answers, so that you can check the information that the answer is based on.

For example, if you ask the question "How many petals does a rose have?", your passage extractor system might return the answer five, and it includes the following output in the paragraph section of the response metadata:

The flowers of most species have fivepetals, with the exception of Rosa omeiensis and Rosa sericea, which usually have only four. Each petal is divided into two distinct lobes and is usually white or pink, though in a few species yellow or red.

Set Up a Remote Answer System

You can configure Answer Server with remote answer systems, which refer to an answer system on a remote Answer Server.

For these systems, Answer Server forwards the Ask action to the remote server, and adds the results from the remote systems to the response. You can use this option when you have a large number of large answer systems to allow you to split your answer systems over multiple machines.

This section describes how to set up a remote answer system, and configure the details of the remote Answer Server.

Configure a Remote Answer System

The Answer Server configuration file contains information about the remote Answer Server that you want to connect to in your remote systems.

For any remote system, you must configure the host and port details of the remote Answer Server. You can configure it individually for each system, or define a separate configuration section that contains the details. Using a separate configuration might be useful if you have multiple systems that use the same remote Answer Server.

In the remote answer system, you also configure the name of the answer system on the remote server. When your main Answer Server forwards an Ask action to the remote server, it uses this system in the action to retrieve the correct results.

The following procedure describes how to configure a remote system in Answer Server.

For more details about the configuration parameters for the remote system, refer to the Answer Server Reference.

To configure the Remote Answer System

Open the Answer Server configuration file in a text editor.
Find the [Systems] section, or create one if it does not exist. This section contains a list of systems, which refer to the associated configuration sections for each system.
After any existing systems, add an entry for your new remote system. For example:
```
[Systems]
0=MyAnswerBank
1=MyFactBank
2=MyPassageExtractor
3=MyRemoteSystem
```
Create a configuration section for your remote system, with the name that you specified. For example, [MyRemoteSystem].
Set Type to Remote.
Configure the details for the remote Answer Server that contains the full configuration for your answer system, by using one of the following methods:
- In the remote system configuration, set AnswerServerHost and AnswerServerACIPort to the host name and ACI Port of the remote Answer Server.
- Define a separate configuration section that contains the Answer Server host and port details. This option might be useful if you have multiple remote answer systems on the same remote server.
  1. In the remote system configuration, set AnswerServer to the name of a configuration section where you define the Answer Server details. For example, MyRemoteAnswerServer.
  2. Create a configuration section for your remote server, with the name that you specified. For example, [MyRemoteAnswerServer].
  3. In this section, set Host and ACIPort to the host name and ACI Port of the remote Answer Server.
Set any other optional parameters for your system and remote Answer Server (such as SSL settings for the remote server). For more information about the available parameters, see Remote Answer Server Configuration Parameters.
Save and close the configuration file.
Restart Answer Server for your changes to take effect.

For example:

[MyRemoteSystem]
Type=Remote
AnswerSystem=AnswerBank
AnswerServerACIPort=7000
AnswerServerHost=server1.example.com

[MyRemoteSystem2]
Type=Remote
AnswerSystem=FactBank1
AnswerServer=RemoteServer2

[MyRemoteSystem3]
Type=Remote
AnswerSystem=FactBank2
AnswerServer=RemoteServer2

[RemoteServer2]
Host=server2.example.com
ACIPort=7000

Use a Remote Answer System

When you have a remote answer system, Answer Server treats it in the same way as a local answer system when it processes results.

You can include a remote answer system in a query in the same way that you do any local systems. By default, the Ask action retrieves answers from all systems, or you can limit the action to particular systems by setting the SystemNames parameter to a comma-separated list of system configurations. For example:

http://12.3.4.56:7000/action=Ask&Text=What is the largest city in Norway?&SystemNames=FactBank,MyRemoteFactBank

The Ask action is the only action that Answer Server forwards to the remote servers. To manage your systems, for example by using GetResources and ManageResources, you must send the actions directly to the Answer Server where the system is configured.

NOTE: When you send a GetResources action with the SystemName parameter set to the name of a remote answer system, it returns only JSON schemas and XSDs for the GetResources action. To retrieve the full set of XSDs and schemas, you must send the action directly to the remote Answer Server.

Set Up a RAG System

This section describes how to set up a Retrieval Augmented Generation (RAG) system, and configure the subcomponents.

Configure the RAG System

The Answer Server configuration file contains information about the subcomponents in your RAG systems.

For any RAG system, you must configure the host and port details of your data store, which is an Content component that contains the documents that Answer Server uses to find answers. You must also configure the LLM module to use to generate answers.

The following procedure describes how to configure the RAG system in Answer Server.

For more details about the configuration parameters for the RAG system, see RAG System Configuration Parameters.

To configure the RAG System

Open the Answer Server configuration file in a text editor.
Find the [Systems] section, or create one if it does not exist. This section contains a list of systems, which refer to the associated configuration sections for each system.

After any existing systems, add an entry for your new RAG system. For example:

[Systems]
0=MyAnswerBank
1=MyFactBank
2=MyPassageExtractor
3=MyPassageExtractorLLM
4=MyRAG

Create a configuration section for your RAG system, with the name that you specified. For example, [MyRAG].
Set Type to RAG.
Set IDOLHost and IDOLACIPort to the host name and ACI Port of the Content component that contains the documents that you want to use to find answers.

NOTE: If you want to use synonyms to expand queries, set these parameters to the host and port of the Query Manipulation Server (QMS) that provides access to your synonyms. Set the host and port of the Content component in the QMS configuration file instead. For more information about how to enable synonyms, see Use Synonyms to Expand Queries.
Set ModuleID to the name of the configuration section that provides details of the LLM module to use. For information about how to configure this, see [Configure the LLM Module](../Manage Passage Extractor LLM/PassExtLLM_Configure.htm#Configur).
Set the PromptTemplatePath parameter to the path of prompt template to use.
Optionally, set TopicTemplatePath parameter to the path of the topic template to use.
Set MaxQuestionSize and PromptTokenLimit to the maximum numbers of tokens to allow in the question and the complete prompt respectively.
Configure how Answer Server sends queries to the Content component to retrieve candidate documents to use to generate answers.
- If IDOLHost and IDOLACIPort point directly to an Content component, you can optionally set RetrievalType to determine whether to send a conceptual query, a vector search, or a combination.
- If IDOLHost and IDOLACIPort point to QMS, you can use CandidateRetrievalDefaults to configure the query to QMS, and set the QMS QueryType parameter to determine whether to send a conceptual query, a vector search, or a combination. For more information about QueryType, refer to the Query Manipulation Server Help.
Set any other optional parameters for the RAG system. See RAG System Configuration Parameters.
Save and close the configuration file.
Restart Answer Server for your changes to take effect.

For example:

[MyRAG]
Type=RAG
// Data store Content
IdolHost=localhost
IdolAciport=6002

// Module to use
ModuleID=RAGLLM 

//RAG Settings
RetrievalType=mixed
PromptTemplatePath=./rag/prompts/rag_prompt.txt
PromptTokenLimit=1000
MaxQuestionSize=70

[RAGLLM]
Type=GenerativePython 
Script=answerserver\scripts\RAGScript.py

Configure the LLM Module

For a RAG system, you must have an LLM module that defines the script that Answer Server must send the prompts to. Your script must handle connecting to the LLM and sending the prompt. You can use the following types of models:

Generative Lua Script.
Generative Python Script.

When Answer Server receives a question, it creates a query to send to the Content component data store, which returns summaries of the candidate documents. Answer Server uses the original question and these summaries to create the prompt, which it sends to the generation script.

Your script must also include a function that returns information about tokenized text for the tokenizer corresponding to your LLM, to allow Answer Server to construct the prompt with your token limits.

Create a RAG Script

You can use a Lua script or a Python script to perform generative question answering in your RAG system. Answer Server creates the prompt, and your script must handle passing the prompt to the LLM, for example by using an HTTP endpoint.

The script must define two functions:

generate Takes a string (the substituted prompt) and returns a string (the generated answer text).

Answer Server calls this function with the prompt that contains the original question and the retrieved context, to generate the answer.

This function optionally takes a second argument, which is an instance of the GenerationUtils class for Python, or the LuaGenerationUtils class for Lua. This option allows you to access session data for the answer session, which includes previous questions and answers. See Use Session Data.
get_token_count Takes a string (the text to tokenize) and an integer (the limit for the number of tokens that the tokenized text can include). It must return a tuple that contains the truncated input string and the number of tokens that the input string contained before truncation.

Answer Server calls this function to tokenize input text according to the model that you use, to ensure that it uses accurate values when it enforces the maximum question and prompt size limits.

The overall process for the RAG system script is:

Answer Server calls get_token_count when it receives a question, to make sure that the question does not exceed the MaxQuestionSize. It rejects the question if it is too big. If the question is under the limit, Answer Server uses the question size to estimate the amount of space left for contextual document summaries.
If you configure TopicTemplatePath, Answer Server uses the topic template to create a prompt with the conversation history to retrieve the topics. Answer Server calls get_token_count for the topic prompt, which is included in the overall token count for the operation.

Answer Server calls the generate function with the topic prompt and the conversation history. the script uses the prompt to call the LLM and return the conversation topics.
Answer Server generates a query for the question, which includes generating embeddings if you have RetrievalType set to vector or mixed. Answer Server then sends this query to your Content component and retrieves the resulting document summaries. If you used a topic prompt, Answer Server uses the topics in the query to Content to improve the relevance of the results.
Answer Server calls get_token_count again to ensure that the final prompt does not exceed the PromptTokenLimit. Answer Server sends only the context portion of the prompt, with the token_limit set to exclude the tokens already reserved for the question and template text, and any tokens used for the earlier topic prompt. The script truncates the context, if required.
Answer Server uses the truncated context to create the final prompt.
Answer Server calls the generate function with the final prompt and any session data provided. The script uses the prompt and session data to call the LLM and generate your answer.

Lua Example

The following example provides an outline of the required Lua script functions, including a simple example for tokenization.

function generate(prompt)
    -- Sample generative prompt function.
    return "The answer is: " .. prompt
end

function get_token_count(text, token_limit)
    -- Sample get_token_count function.
    local text_split, count = {}, 0
    for word in string.gmatch(text, "%S+") do
        count = count + 1
        if count <= token_limit then
            table.insert(text_split, word)
        end
    end

    return table.concat(text_split, " "), count
end

Python Example

The following example provides an outline of the required Python script functions, including a simple example for tokenization.

def generate(prompt: str) -> str:
    '''
    Sample generative prompt function.
    '''
    return f'The answer is: {prompt}'

def get_token_count(text: str, token_limit: int) -> Tuple[str, int]:
    '''
    Sample get_token_count function.
    '''
    text_split = text.split(' ')
    return ' '.join(text_split[0 : token_limit]), len(text_split)

TIP: You can provide a requirements.txt file for any third-party modules that you want to use, by setting the RequirementsFile parameter in your model configuration. See Configure the LLM Module.

Configure the LLM Module

After you create your Lua or Python script, you must configure an LLM module section in your configuration file, which you refer to in your RAG system configuration.

To configure the LLM Module

Open the Answer Server configuration file in a text editor.
Create a new configuration section for your LLM module. This is the configuration section name that you use in the ModuleID parameter when you configure the RAG system. For example [RAGModule]
In the new configuration section, set the Type parameter to one of the following values:
- GenerativeLua. Use a Lua script to generate answers based on information in your Knowledge Discovery documents.
- GenerativePython. Use a Python script to generate answers based on information in your Knowledge Discovery documents.
Set the required parameters for your module type:
- For a module that uses a Lua script (that is, when Type is set to GenerativeLua), set Script to the path and file name for your Lua script.
- For a module that uses a Python script (that is when Type is set to GenerativePython), set Script to the path and file name for your Python script. You can optionally set RequirementsFile to define modules that your script uses.
For example:
```
[GenerativeQuestionAnsweringLuaScript]
Type=GenerativeLua
Script=LLMscripts/generative_script.lua

[GenerativeQuestionAnsweringPythonScript]
Type=GenerativePython
Script=LLMscripts/generative_script.py
```
Save and close the configuration file.

Use Session Data

When you send an Ask action to the RAG system, you can add the CustomizationData parameter to include session data, which provides previous questions and answers from the question answering session. You can access these past questions and answers from your generative script and use it to modify the prompt that you send to the LLM.

For example, you can use this option to include a chat history in your prompt, which the LLM can use to generate its answer.

You access the session data by passing a second argument to your generate function in your GenerativePython or GenerativeLua script.

Python

The second argument to your generate function is an instance of the GenerationUtils class which has the following interface:

class GenerationUtils:
    '''
    Utility class for additional functionality when using generative LLM Python scripts.
    '''
    @property
    def session_data(self) -> list[dict[str, str]]:
        '''
        A collection of dictionaries, each with 'question' and 'answer' keys that hold
        information about results for previous questions asked on a particular session.
        '''

This interface is provided as part of a generation_utils.pyi stub file, which is included in the tools directory of your Answer Server installation.

You can then access the session data as a list of dicts by using the session_data property:

def generate(prompt: str, generation_utils: 'GenerationUtils') -> str:
    '''
    Sample generative prompt function.
    '''
    conversation_history = ""
    for conversation_entry in generation_utils.session_data:
        question = conversation_entry.get("question", "N/A")
        answer = conversation_entry.get("answer", "N/A")
        conversation_history += f"{question}: {answer}\n"

    final_prompt = f'''
                    {prompt}
                    You may use the following conversation history in your generated answer:
                    {conversation_history}
                    '''
    dummy_model = lambda prompt: f"Generated response based on: {prompt}"
    return dummy_model(final_prompt)

Lua

The second argument to your generate function is an instance of the LuaGenerationUtils class. This class provides one helper method session_data(), which returns an array of tables, each with a question and answer entry. For example:

function generate(prompt, generation_utils)
    local session = generation_utils:session_data()
    local history = {}
    for _,step in ipairs(session) do
        table.insert(result, "Question: " .. step.question)
        table.insert(result, "Answer: " .. step.answer)
    end
    history = table.concat(history, "\n")
    -- Now pass history + prompt to LLM to create result
    -- ...
    -- and return the answer, whatever it was
    return answer
end

Use System Groups

This section describes how to configure system groups in Answer Server to request answers from multiple systems.

Configure a System Group

An Answer Server system group is a set of answer systems that you want to retrieve answers from by sending a single system name to the Ask action.

You can use system groups to make it easier to send Ask actions to multiple systems that you generally use together. For example, you might create a group based on language or system type.

In particular, system groups might be useful if you have a custom user interface to ask questions and your systems might change regularly. In this case, you can use a static set of groups and change the Answer Server configuration to update the systems, rather than changing the user interface.

To configure system groups

Open your configuration file in a text editor.
Create an [AnswerSystemGroups] configuration section.
In the [AnswerSystemGroups], add a parameter 0, and set it to the name of a configuration section that you want to use to define the first group. For the next group, add a parameter 1, and so on. For example:
```
[AnswerSystemGroups]
0=AllEnglish
1=AllFrench
2=AllFactBank
```
For each group that you configure in [AnswerSystemGroups], create a new configuration section with the same name (for example [AllEnglish], [AllFrench], and [AllFactBank].
In the group configuration section, add a parameter 0, and set it to the name of the first system to include in this group. The system name must match the name of the configuration section where you have configured the system. Add a parameter 1 for the second system, and so on. For example:
```
[AllEnglish]
0=FactBankEnglish
1=AnswerBankEnglish
2=PassageExtractorEnglish
```
In this example, the AllEnglish system refers to three other systems, FactBankEnglish, AnswerBankEnglish, and PassageExtractorEnglish.

NOTE: When you send an Ask action to the system group, Answer Server attempts to retrieve answers from the systems in the order that you configure them in the system group. See Ask Questions to a System Group.
Repeat step 5 for any other system groups that you want to configure.
Save and close the configuration file.

The following example configures three system groups:

[AnswerSystemGroups]
0=AllEnglish
1=AllFrench
2=AllFactBank

[AllEnglish]
0=FactBankEnglish
1=AnswerBankEnglish
2=PassageExtractorEnglish

[AllFrench]
0=FactBankFrench
1=AnswerBankFrench
2=PassageExtractorFrench

[AllFactBank]
0=FactBankEnglish
1=FactBankFrench
2=FactBankGerman

Ask Questions to a System Group

When you have configured system groups, you can use them in the Ask action in the same way as individual systems. When you add a system group to the SystemNames parameter, Answer Server sends the Ask action to all the systems in that group.

For example:

http://localhost:12000?Action=Ask&Text=Who won the award for Best Picture in 2012?&SystemNames=AllEnglish,AllFactBank

When you send the Ask action to a system group rather than individual systems, Answer Server sends the action to the groups in the order that you specify them in SystemNames. In each group, it sends the action to the systems in the order that you configure them in the group.

You can include a combination of groups and individual systems in SystemNames.

NOTE: If you specify a particular system more than once in the Ask action (for example because it occurs in more than one specified group), Answer Server sends the action to it only once, the first time it occurs.

Ask Questions in Answer Server

This section describes how to ask questions and get answers from Answer Server.

Ask a Question

To get answers from Answer Server, use the Ask action. Specify the question text in the Text parameter. For example:

http://localhost:12000?Action=Ask&Text=Who won the award for Best Picture in 2012?

The Ask action also has a number of optional parameters to allow you to tune your results.

SystemNames restricts the Ask action to particular configured systems or system groups. For example:

http://localhost:12000?Action=Ask&Text=Who won the award for Best Picture in 2012?&SystemNames=MovieFactBank,Answerbank

By default, Answer Server sends the question to all configured systems, in the order in which they are configured in the [Systems] section. If you set SystemNames, Answer Server sends the question only to the specified systems, in the order in which you specify them.
MaxResults specifies the maximum number of results to retrieve.

http://localhost:12000?Action=Ask&Text=Who won the award for Best Picture in 2012?&SystemNames=MovieFactBank,Answerbank&MaxResults=2

In this case (for default sorting), if Answer Server finds the required number of results from the first system, it does not request answers from further systems.
Sort specifies how to sort the results. By default, Answer Server sorts answers in the order of the system that the answer comes from (either the configured order, or the order in SystemNames). You can set Sort to Confidence instead, to sort the results by score.

http://localhost:12000?Action=Ask&Text=Who won the award for Best Picture in 2012?&MaxResults=2&Sort=Confidence&SystemNames=MovieFactBank

NOTE: Each answer system in Answer Server scores its answers independently, so scores from one system might not be comparable to scores from another.
MinScore specifies the minimum score that an answer must have for it to return as a result.
CustomizationData specifies additional information to include in the request. For a fact bank or passage extractor system, you can use this option to include a security info string. In this case, fact bank returns only facts that the user has access to, and passage extractor returns answers only if they appear in documents that the user has access to.

Action=Ask&Text=What is the gift and entertainment policy?&CustomizationData=[{"system_name":"MyPassageExtractor", "security_info": "MTQ0lGDBkNrJvBv0pOi+QDBK1z6y/1/09BqL4Vu/18W7JGCy8Pvm4/wixO/pI99/A=="}]

For an answer bank system, you can use this option to supply additional FieldText to provide in the query to the answer bank Agentstore. This option allows you to restrict the Ask action to a subset of your Answer Bank data (for example, content relevant to a particular region), without having to set up multiple Answer Bank systems and Agentstores.

Action=Ask&Text=What is the gift and entertainment policy?&CustomizationData=[{"system_name":"MyAnswerBank", "fieldtext": "MATCH{UK,EUROPE}:REGION"}]

TIP: You can add the custom fields to your question equivalence classes as metadata. See Create a Question Equivalence Class and Add an Answer.

You can retrieve the full schema for the JSON object to use in CustomizationData by using the GetResources action. See Find the JSON Schema for Your Update.

For more information about the Ask action, refer to the Answer Server Reference.

Use Context in the Ask Action

You can apply a context to a question that you send with the Ask action. The context specifies additional information to limit the scope of the question. In Fact Bank the context is a specific entity used in disambiguation, for example, you might set a context to specify that a user is asking questions about Cambridge UK, rather than Cambridge Massachusetts or Ontario. For Answer Bank or Passage Extractor, the context is a string that might, for example, come from a previous question.

When you include a valid Context ID with a question using the Ask action, the system caches the answer-system context associated with each answer. The response includes answers with a context tag which has a token attribute. A token can be used to update the context using the ManageResources action.

Tokens remain valid until the next time the user asks a question using that Context ID.

You can create an empty context to save tokens for use in a future context update, by using the ManageResources action to return a Context ID for an empty context. Then you can ask a question using the Ask action and the new Context ID. Returned answers from all answer systems then have a context tag with token attribute. To use the context for subsequent questions, select the appropriate answer, and update the Context in ManageResources with the context token for that answer. Specifying a token loads the associated system context from the cache into the current context.

Create a Context

You create a question context by using the ManageResources action. You do not set a system name in the ManageResources action. You can create an empty context to save a token for use with future context updates.

NOTE: Each question context that you create uses a licensed conversation slot (in the same way as conversation sessions). ManageResources returns an error if you do not have enough capacity. In this case, you must wait until a conversation session or question context expires, or delete one before you can create another. See Configure Context Expiration.

You can define a context in a Fact Bank instance by using an entity code.

action=ManageResources  
Data={
   "type": "context",
   "operation": "add",
   "context": [{
      "system_name": "factbank1",
      "data": [{
         "code_type": "entity",
         "name": "Cambridge",
         "codes": ["Q350"]
      }]
   }]
}

In this example, the code Q350 corresponds to Cambridge UK.

You can define a context in an Answer Bank instance by using a context string.

action=ManageResources  
Data={
    "type": "context",
    "operation": "add",
    "context": [{
        "system_name": "answerbank1",
        "data": {
            "subject": ["MyCompany"]
        }
    }]
}

In this example, "MyCompany" could be a context returned from a previous question.

You can define a context in a Passage Extractor instance by using a context string.

action=ManageResources  
Data={
    "type": "context",
    "operation": "add",
    "context": [{
        "system_name": "passageextractor1",
        "data": {
            "context": ["france"]
        }
    }]
}

In this example, "france" could be a context returned from a previous question.

You can define an empty context without the context entity code or context string that would be required if creating a context in a specific answer system.

action=ManageResources
Data={
    "type": "context",
    "operation": "add"
}

This can be use to save a token for use with future context updates.

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

The action returns an ID, which you can use in the Ask action to set the context for a question.

TIP: You can also retrieve the question context ID by sending a GetResources action with the Type parameter set to context.

Use a Question Context

When you have a question context ID, you can send it in the Ask action Context parameter. For example:

action=Ask&Text=What is its population?&Context=860028728520387723

If this is the ID for the context created in the Fact Bank example above, this action returns the population of Cambridge UK.

Configure Context Expiration

Question contexts use conversation session license slots. To ensure that you do not run out of conversation sessions or question contexts, you can:

manually delete the contexts by using the ManageResources action.
configure context expiration so that Answer Server automatically deletes unused contexts.

To configure context expiration, you can set the ExpirationIdleTime and ExpirationInterval configuration parameters in the [AskContext] section of your configuration file. For example:

[AskContext]  
ExpirationIdleTime=600  
ExpirationInterval=30

Retrieve All Facts About an Entity

You can retrieve all facts that relate to a particular entity by using the Report action. This action applies only to Fact Bank systems that use a SQL database backend. You specify an entity, and this action returns all facts in your Fact Bank that include this entity as the entity, or as a property or qualifier value.

For example:

http://localhost:12000?Action=Report&Entity=Cambridge

Set Up a Conversation System

This section describes how to set up a Conversation system, and configure the subcomponents.

Configure the Conversation System

The Answer Server configuration file contains information about the subcomponents and settings for your Conversation systems.

For any Conversation system, you must configure the name of a JSON task configuration file, which defines the conversation task in detail. For details about how to create this file, see Create a Task Configuration File.

The following procedure describes how to configure the Conversation system in Answer Server.

In addition, you can optionally configure session expiration for your conversation sessions, and settings for an Agentstore component that contains triggers for your conversation sessions.

For more details about the configuration parameters for the Conversation system, refer to the Answer Server Reference.

To configure the Conversation System

Open the Answer Server configuration file in a text editor.
Find the [Systems] section, or create one if it does not exist. This section contains a list of systems, which refer to the associated configuration sections for each system.
After any existing systems, add an entry for your new Conversation system. For example:
```
[Systems]
0=MyAnswerBank
1=MyFactBank
2=MyPassageExtractor
3=MyConversation
```
Create a configuration section for your Conversation system, with the name that you specified. For example, [MyConversation].
Set Type to Conversation.
Set TaskConfigurationFile to the path and file name of the JSON file that contains your task configuration file. You can also specify a comma-separated list of path and file names if you have split your task configuration across multiple files.
Optionally set any additional settings for your conversation system. For more information, see Conversation System Configuration Parameters.
Save and close the configuration file.
Restart Answer Server for your changes to take effect.

For example:

[MyConversation]
Type=Conversation
TaskConfigurationFile=C:\AnswerServer\Conversation\tasks.json
// Trigger Agentstore
AgentStoreHost=localhost
AgentStoreAciport=5002
// Session Expiration
SessionExpirationIdleTime=600
SessionExpirationInterval=60

Create a Task Configuration File

The Conversation task configuration file describes all the settings for a particular conversation task, including prompts, triggers, response validation, and the details of Lua scripts to run.

You can retrieve the full schema for the task configuration JSON file by sending the GetResources action with the Type parameter set to Schema.

TIP: For ease of maintenance, you can split your task configuration across multiple JSON files. Answer Server merges the configurations together when it runs.

The task configuration file contains one or more conversation tasks. Each task must contain a unique ID (id). You can also set a display_id, which is a user friendly display name that Answer Server uses in a disambiguation message when user input matches the triggers for more than one task (see Conversation Triggers).

The other options you use in a task depend on what you want to the task to do. The following sections describe the main options that you can use in task configuration:

Pre-Task Actions. Pre-task actions run at the start of the task. You can use pre-task actions to set an initial prompt for the task, by setting some text or by specifying a Lua function to run to generate a prompt.
Conversation Triggers. A conversation trigger defines when to run a particular conversation task. You can use several different types of trigger to activate a particular task by matching user text against a simple word list, a regular expression pattern, or an agent.
Task Requirements. Task requirements request pieces of information that the user must provide before Answer Server can complete the tasks. You can save the requirement result as a variable, either for the duration of the task or for the whole conversation session.
Post-Task Actions. Post-task actions run at the end of the task, after all the requirements have been satisfied. You can use post-task actions to send an acknowledgment to confirm that the requirements are met, or to call a Lua function to perform an external operation.
Task Routing. Routing allows you to specify the task to run after the current task. You can route directly to a particular task, or you can use a further prompt to allow you to route to another task depending on user input.
Response Validation. Response validation allows you to check that the user provides a response that you can use in the task, and to deal with the response if it is not valid. You can validate the response by using a simple word list, a regular expression, Named Entity Recognition, or a Lua script.
Lua Processing Scripts. You can use Lua functions in your task configurations to run additional more complicated operations, and to send calls to external systems to complete tasks. You configure a single Lua script in your task configuration, and then call individual functions. You can use functions to generate a custom preamble for a task, to perform an operation at the end of the task, and you can use Lua functions for response validation and to process user input that is not valid.

In addition to the task configuration, and the associated validator configuration, the task configuration file also contains:

Initial Task. The ID of the first task to run when the conversation session starts, if you do not have any initial user text. You must include an initial task in your task configuration.
Fallback Task. The ID of a task to run when there are no other active tasks. You must include a fallback task in your task configuration.
Default Messages. Custom text to use for default responses, such as when the user does not provide any valid input, or to provide the user with disambiguation options when their text triggers more than one task. There are default values for these messages, which you can override with your own values (for example, if you want to create conversations in a different language).
Task Cancellation. Settings that determine how to allow users or the system to cancel a task, and what to do when a task is canceled.

Pre-Task Actions

Pre-task actions run before the main part of the task. When user input triggers a particular task, Answer Server runs the pre-task actions before checking for requirements. The main use of this option is to provide an initial prompt at the start of the task.

To configure pre-task actions, you set the pre object in the configuration object for an individual task.

The pre object is not required. If you do not add a pre object to the task, Answer Server runs the next step of the task, for example processing and gathering the requirements.

The following table describes the properties that you can set in the pre object.

Property	Type	Description
`response`	string	(Optional) A string response to return to the user. For example, this might be an introductory sentence to start the task.
`lua`	string	(Optional) A lua function to run before the rest of the task, for example to generate a dynamic task preamble response. The function that you specify must accept a `taskUtils` object. See Lua Processing Scripts.

{
   "tasks" : [
      {
         "id" : "GREET",
         "pre" : {
            "response" : "Hello and Welcome to the Virtual Assistant. How can I help you?"
         },
         "trigger" : {
            "simple" : {
               "phrases" : [ 
                  "hello",
                  "hi"
               ]
            }
         }
      }
   ]
}

Conversation Triggers

A conversation trigger defines when to run a particular conversation task. When you start a conversation session, or when a user provides text, Answer Server finds the conversation trigger that matches the input, and runs the appropriate task.

You can use several different types of triggers:

Agent. Trigger a task based on a match against your Conversation Agentstore index. To use this option you must configure an Agentstore component in your Conversation system configuration. See Configure the Conversation Agentstore.
Regular Expressions. Trigger a task based on a text match against a regular expression pattern.
Simple. Trigger a task based on a simple exact phrase match.

You can configure different tasks with different types of triggers.

TIP: When a user sends some text that matches more than one trigger, Answer Server returns a disambiguation prompt. This prompt uses the display_id in your tasks to display the options to the user. See Task Disambiguation.

Not all tasks require a conversation trigger. For example, the tasks that you configure as the initial task and fallback task might not need a trigger (see Default Tasks). Similarly, you might have tasks that run only when called by explicit routing from another task.

The number of tasks that you add triggers to depends on your conversation structure and routing.

To configure a trigger, you set the trigger property in the configuration object for an individual task, which contains different properties depending on the type of trigger you use.

The following sections describe the types of conversation triggers in more detail, and provide examples of how to configure them.

Agent Triggers

NOTE: To use agent triggers, you must configure an Agentstore component in your Conversation system configuration.

Agent triggers use Knowledge Discovery agent search to find matching triggers. In agent search, you send plain text or a document to the Agentstore, which returns any agents that match the input text. In the case of agent triggers, Answer Server sends the user input text to the Agentstore, which returns any matching agent triggers.

You link the value of an Agentstore field in the trigger agent (usually the document reference) to a task in your task configuration JSON file. When the user text matches a particular agent trigger, Answer Server runs the corresponding task for that agent.

TIP: By default, Answer Server uses the document reference field in your agents as the task ID. You can set the AgentstoreReferenceField configuration parameter in your Conversation system configuration to change the field that Answer Server uses as the task ID.

Agent triggers use Knowledge Discovery text search to match user text. For example, it includes stemming to allow more flexible term matching, and you can use term weighting to influence how triggers match. For more information, refer to the Knowledge Discovery Administration Guide.

To configure an agent trigger, you add a trigger object with the agent property, set to the document reference for the agent that triggers the task.

For example:

The following IDX document represents a simple agent trigger, which you index into the Conversation Agentstore:

#DREREFERENCE LunchConversationTrigger
#DREDATE 2017/07/01
#DRETITLE
Lunch
#DRECONTENT
food lunch sandwich
#DREDBNAME MyAgentDB
#DREENDDOC

The following JSON shows a task that uses this agent as a trigger.

{
   "tasks" : [
      {

         "id" : "LUNCH",
         "pre" : {
            "response" : "I can help you order some lunch."
         },
         "trigger" : {
            "agent" : "LunchConversationTrigger"
         }
      }
   ]
}

This task runs when a user sends any text that matches the terms food, lunch, or sandwich in Knowledge Discovery text matching.

Regular Expressions Triggers

Regular expressions triggers match user text against a regular expression pattern that you provide in the task configuration. Answer Server runs the task when the user input text matches your regex.

To configure a regular expressions trigger, you add a trigger object with the regex property. The regex property contains a pattern subproperty, which you must set to a regular expression pattern in ECMAScript regular expression format.

For example:

{
   "tasks" : [
      {
         "id" : "LUNCH",
         "display_id" : "order lunch",
         "pre" : {
            "response" : "I can help you order some lunch."
         },
         "trigger" : {
            "regex" : {
               "pattern" : "(Book|order) .* lunch"
            }
         }
      }
   ]
}

You can also provide a weight for the trigger by setting the weight property in the trigger object. The weight value is a number between one and 100. The default value is 100. Answer Server uses this weight to determine the best triggers to return in a disambiguation response. See Trigger Options.

The weight value is constant for a particular trigger. You can assign a higher weight to triggers that have more restrictive trigger conditions. For example, if a user must match a more complex regular expression to trigger a task, it is more likely to be the task that they want, and so you assign a higher weight.

For example:

 "trigger" : {
   "regex" : {
      "pattern" : "(Book|order) .* lunch"
   },
   "weight" : 80
}

Simple Triggers

Simple triggers match user text against a list of phrases that you provide in the task configuration. Answer Server runs the task when the user input text matches one of the phrases you provide.

In a simple trigger, you must provide a list of phrases. You can optionally also provide a required prefix and suffix. By default, matches are case sensitive, but you can also use a property in your configuration to specify that matches must be case insensitive.

To configure a simple trigger, you add a trigger object with the simple_match property. The following table describes the subproperties that you can set in the simple_match object.

Property	Type	Description
`phrases`	array, strings	(Required) A list of phrases that you want to match. The task runs if the user input text matches at least one of the specified strings. The array must have at least one item.
`prefix`	string	(Optional) A string that must occur at the start of the user input text for this trigger to match.
`suffix`	string	(Optional) A string that must occur at the end of the user input text for this trigger to match.
`case_insensitive`	Boolean	(Optional) Set to true to match user text case insensitively. The default value is false (case sensitive matching).

For example:

{
   "tasks" : [
      {
         "id" : "LUNCH",
         "display_id" : "order lunch",
         "pre" : {
            "response" : "I can help you order some lunch."
         },
         "trigger" : {
            "simple_match" : {
               "prefix" : "I want to",
               "phrases" : [ 
                  "order some lunch",
                  "buy a sandwich",
                  "book a table for lunch",
                  "order food"
               ]
            }
         }
      },
      {
         "id" : "BREAKFAST",
         "display_id" : "order breakfast",
         "pre" : {
            "response" : "I can help you order some breakfast."
         },
         "trigger" : {
            "simple_match" : {
               "phrases" : [ 
                  "get breakfast",
                  "order breakfast",
                  "eat breakfast",
                  "buy breakfast"
               ],
               "case_insensitive" : true
            }
         }
      }
   ]
}

The first of these example tasks matches user text that starts with I want to and continues with one of the listed phrases, such as I want to order some lunch, or I want to order a sandwich. The matching for this task is case sensitive.

The second task matches user text that contains any of the listed phrases, and matches case insensitively.

The weight value is constant for a particular trigger. You can assign a higher weight to triggers that have more restrictive trigger conditions. For example, if a user must supply more matching keywords to trigger a task, it is more likely to be the task that they want, and so you assign a higher weight.

For example:

"trigger" : {
   "simple_match" : {
      "phrases" : [
         "get breakfast",
         "order breakfast",
         "eat breakfast",
         "buy breakfast"
         ],
      "case_insensitive" : true
   },
   "weight": 90
}

Task Disambiguation

In some cases, the user might provide text that matches the trigger for more than one task. In this case, Answer Server returns a disambiguation prompt, which allows the user to select the appropriate option from a list of tasks that match their input.

Answer Server uses the task display_id property in the prompt that it displays to the user. If you do not specify a display_id, it uses the id property.

For example:

{
   "tasks" : [
      {
         "id" : "LUNCH",
         "display_id" : "order lunch",
         "pre" : {
            "response" : "I can help you order some lunch."
         },
         "trigger" : {
            "simple_match" : {
               "prefix" : "I want to",
               "phrases" : [ 
                  "order food"
               ]
            }
         }
      },
      {
         "id" : "BREAKFAST",
         "display_id" : "order breakfast",
         "pre" : {
            "response" : "I can help you order some lunch."
         },
         "trigger" : {
            "simple_match" : {
               "phrases" : [ 
                  "get breakfast",
                  "order breakfast",
                  "eat breakfast",
                  "buy breakfast",
                  "order food"
               ]
            }
         }
      }
   ]
}

If a user sends the text I want to order food, both of these task triggers match. Answer Server then returns the text Which of the following did you mean: order lunch, or order breakfast? (you can modify this message, if required. See Default Messages).

After the user selects the appropriate task, Answer Server processes the selected task. It sends the original text that activated the disambiguation prompt to the new task, so that the new task can use it for automatic requirement gathering, where appropriate (see Automatic Requirement Gathering).

You can define the maximum number of triggered tasks that return in a disambiguation message by using the trigger_options configuration. See Trigger Options.

Trigger Options

The trigger_options object allows you to set additional properties that define how your task triggers work. You can optionally add this object at the top level of your task configuration file. The settings apply to all your tasks.

The following table describes the properties that you can set in the trigger_options object.

Property	Type	Description
`max_triggers`	integer	(Optional) The maximum number of triggers that the conversation task can return in a disambiguation response. Answer Server sorts the triggers by weight and returns up to `max_triggers` options with the highest weight. The default value is 6. For non-agent triggers, you define the `weight` property in the `trigger` configuration object. For agent triggers, Answer Server uses the returned `autn:weight` value when it queries for matching agent triggers. Answer Server considers triggers with zero weight only if there are no matches with non-zero weights.
`weight_range`	number(0-100)	(Optional) The weight range for task triggers to allow in task disambiguation. When Answer Server returns a disambiguation response, it does not return any triggers that have a weight that is more than `weight_range` below the highest weight. By default, there is no limit.

For example:

{  
   "tasks" : ...
   "trigger_options": {
      "max_triggers": 5,
      "weight_range": 50
   }
}

Task Requirements

Task requirements specify a piece of information that the user must provide before Answer Server can complete the task. Tasks can have multiple requirements.

When a user provides information to satisfy a requirement, Answer Server updates a variable. It stores the variable to use later in the task (for example to send information to an external system). By default, Answer Server stores the variable only for the duration of the current task. You can also choose to store a variable for the whole conversation session.

To configure requirements, you set the requirements property in the configuration object for an individual task. The requirements property takes an array of requirement objects. The following table describes the properties that you use to define a requirement.

Property	Type	Description
`id`	string	(Required) A unique ID for the requirement. Answer Server uses this value as the name of the task or session variable that it stores for this requirement.
`prompt`	string	(Required) The prompt to send to the user to request the information. You can include session and task variables, by inserting the variable ID in double curly brackets, for example `{{MYVARIABLE}}`. The variable must already be set in an earlier part of the task (for a task variable) or conversation session (for a session variable). You can optionally use the `task:` or `session:` prefix to specify the type of variable, for example `{{task:MYVARIABLE}}`. If you do not use a prefix, Answer Server searches for the variable in the task variables first, and then the session variables.
`scope`	enum, string	(Optional) The scope of the variable: `local` or `session`. The default value is `local`, which means that the variable is available only in the current instance of the current task. Set scope to `session` to store the variable for the whole conversation session.
`validation`	array, strings	(Optional) A list of validators to use to validate the user input. Specify the ID of each validator that you want to use to validate the current requirement. You define the validators separately in the `validators` section of the task configuration JSON file. See Response Validation.
`prompt_required`	Boolean	(Optional) Set to true to require that the prompt for this requirement must be sent to the user before this requirement can be set. By default, Answer Server attempts to answer requirements from the trigger or subsequent user text, unless the requirement does not have any validators (in which case, Answer Server always presents the prompt, and the prompt for the next requirement). For more details, see Automatic Requirement Gathering.
`ask_options`	object	(Optional) Options to use for the `Ask` action when the user text does not pass the requirement validators. By default, if the user text is not valid, the conversation system returns a default message. You can set `ask_options` if you want to treat user text that is not a valid answer for the requirement as a question to ask in your other answer systems. The `ask_options` JSON object can contain the following properties: * `max_results` (number) Required. The maximum number of results to retrieve from the other answer systems. * `systems` (array, strings) Optional. The systems that you want to send the `Ask` action to.
`suggestions`	array, strings	(Optional) A list of suggested answers to return to the user with the requirement prompt. When you set this option, Answer Server returns the suggestions with the prompt in the `Converse` action response. You can use these values to present suggestions to your users. Answer Server does not validate the configured suggestions. However, it does validate the user responses that include them, so OpenText strongly recommends that you use valid values as suggestions. You can include session and task variables, by inserting the variable ID in double curly brackets, for example `{{MYVARIABLE}}`. The variable must already be set in an earlier part of the task (for a task variable) or conversation session (for a session variable). You can optionally use the `task:` or `session:` prefix to specify the type of variable, for example `{{task:MYVARIABLE}}`. If you do not use a prefix, Answer Server searches for the variable in the task variables first, and then the session variables.
`user_cancel`	object	(Optional) An object that defines keywords that a user can use to cancel a task, and the action to perform if they do. For details of the configuration properties, see User Cancellation. The `user_cancel` options in the requirements section override any values that you set in the main task configuration or for the individual task.
`system_cancel`	object	(Optional) An object that defines what actions to take when the requirement receives multiple non-valid responses. For details of the configuration properties, see System Cancellation. The `system_cancel` options in the requirements section override any values that you set in the main task configuration or for the individual task.

When Answer Server runs a task that has requirements, it returns the pre response for the task (if present), and then the prompt for the first requirement. Each prompt returns in a separate <prompt> tag in the same Converse action response, and you can choose how to display this information in your user interface.

For example:

{
   "initial_task" : "GREET",
   "tasks" : [
      {
         "id" : "GREET",
         "pre" : {
            "response" : "Hello and welcome to the Virtual Assistant. Before we get started, I'd like to ask you a couple of questions."
         },
         "requirements": [ 
            {
               "id": "USER_NAME",
               "prompt": "What is your name?",
               "prompt_required": true,
               "scope": "session"
            }, 
            {
               "id": "USER_COUNTRY",
               "prompt": "What country do you live in?",
               "prompt_required": true,
               "validation": [ "VALIDATE_COUNTRIES" ]
            }
         ]
      }
   ],
   "validators": [
      {
         "id": "VALIDATE_COUNTRIES",
         "eduction": {
            "grammars": "place_countries.ecr"
         }
      }
   ]
}

When the task runs at the start of a conversation session, the user receives the following initial message:

Hello and welcome to the Virtual Assistant. Before we get started, I'd like to ask you a couple of questions.
What is your name?

When the user answers, the task stores the answer in the USER_NAME session variable and then returns the following message:

What country do you live in?

Answer Server validates the user input by using the VALIDATE_COUNTRIES validator. For more information about validator configuration, see Response Validation. If the response is valid, Answer Server stores the value in the USER_COUNTRY task variable.

Automatic Requirement Gathering

The example in the previous section uses the prompt_required flag to ensure that Answer Server sends the prompt to the user, and the user must provide an answer to each requirement individually.

In many cases, you might want to automatically check the user response text for additional answers to your task requirements. For example, if you send a prompt to a user for their name, and they reply with their name and company, you might want to extract the company name from this text, rather than subsequently asking the user what company they work for.

Automatic requirement gathering applies only to requirements that have validators, and where the prompt is not required. When a user sends some text, Answer Server checks whether any portion of their input text matches the validator for the current requirement. If it does, it also checks whether the user input text matches the validators for any other requirements in the current tasks, and sets the appropriate task and session variables if it does.

NOTE: For requirements that do not have validators (for example, those with free text input), Answer Server always presents the prompt. It also always presents the prompt for the following requirement, even if the user provided the information in an earlier response.

This process applies to the initial user text that triggers the task. If the trigger text contains the answer for the first requirement in the task, Answer Server also checks whether the text contains answers for other requirements.

For example:

{
   "tasks" : [
      {
         "id" : "LUNCH",
         "pre" : {
            "response" : "I can help you order some lunch."
         },
         "trigger" : {
            "regex" : {
               "pattern" : "(Book|order) .* lunch"
            }
         },
         "requirements": [ 
            {
               "id": "FOOD_TYPE",
               "prompt": "Do you feel like a sandwich or a panini?",
               "validation": [ "FOODTYPEVALIDATOR" ]
            }, 
            {
               "id": "FILLING",
               "prompt": "What filling would you like?",
               "validation": [ "FILLINGVALIDATOR" ],
               "suggestions": ["cheese", "ham", "turkey"]
            }
         ],
         "post" : {
            "response" : "We'll get you a {{FILLING}} {{FOOD_TYPE}} right away!"
         }
      }
   ],
   "validators" : [
      {
         "id" : "FOODTYPEVALIDATOR",
         "simple" : {
            "matches": [
               { "values": [ "sandwich", "panini" ] }
            ]
         }
      },
      {
         "id" : "FILLINGVALIDATOR",
         "simple" : {
            "matches": [
               { "values": [ "cheese", "ham", "turkey" ] }
            ]
         }
      }    
   ]
}

If a user triggers this task with the text I want to order some lunch, Answer Server returns the prompt for the first requirement as usual. However, if the user triggers the task with the text I want to order a cheese panini for lunch, the trigger text provides the answer to both of the requirements. In this case, Answer Server responds with the initial task prompt (I can help you order some lunch), and the acknowledgment (We'll get you a cheese panini right away).

Response Validation

Response validation allows you to check that the user response contains the information you need to complete a task, or route to an appropriate task. You use validators in the requirements for your tasks (see Task Requirements).

You can use several different types of validation:

Simple. Validate against a simple list of words and phrases, which the user input must match exactly.
Regular expression. Validate against a regular expression pattern, which the user input must match.
Named Entity Recognition (Eduction). Validate against a set of Named Entity Recognition grammars and entities. This validator uses the embedded Answer Server Named Entity Recognition module.
Lua. Validate by using a Lua function. This validator calls a function in an external Lua script, which you must configure in the task configuration file. See Lua Processing Scripts.

You configure validators in the validators section of the task configuration file. This property takes an array of validators. Each validator must contain a unique ID, and a configuration object (one of simple, regex, eduction, and lua, depending on the validation type). The following sections describe each type of validator configuration in more detail, and provide examples of each type of validator.

Each validator object can also optionally include the properties in the following table.

Property	Type	Description
`invalid_input_lua`	string	(Optional) A Lua function in the configured Lua script to call if the user input is not valid. For example, you might use this to submit the user response to your other answer systems. See Lua Processing Scripts.
`inverted`	Boolean	(Optional) Set to true if you want to invert the match (that is, to consider user input text as valid if it does not match the validator). The default value is false (user input text must match the validator).

Simple Validation

In simple validation, you provide a simple list of values that the user input must match.

The following table describes the properties that you can set in the simple validation configuration object.

Property	Type	Description
`matches`	array, objects	One or more match JSON objects, which contain the following properties: * `values` (array, strings) Required. A list of values that you want to accept as user input for this validator. Answer Server accepts these values if they appear as part of a sentence in the input. * `return_value` (string) Optional. The value that the validator uses if the user input matches any of the values in the array. If you do not set this value, the validator returns the value that was matched in the user input.
`case_insensitive`	Boolean	(Optional) Set to true if you want to match values case insensitively. The default value is false (case sensitive matching).

For example:

{
   "tasks": [
      ...
   ]
   "validators": [
      {
         "id" : "UKcountryname",
         "simple" : {
            "matches": [
               {
                  "values": [ "United Kingdom", "UK", "Great Britain", "GB" ],
                  "return_value": "UK" 
               },
               {
                  "values": [ "England", "Northern Ireland", "Scotland", "Wales" ] 
               }
            ],
            "case_insensitive" : true
         }
      }
   ]
}

This example validator checks that the user input matches one of the listed names for the United Kingdom. If the user text includes one of United Kingdom, UK, Great Britain, or GB, the validator returns the value UK to the task. If the user text includes England, Northern Ireland, Scotland, or Wales, the validator returns the value that the user matches.

Regular Expression Validator

In regular expression validation, you provide a regular expression pattern that the user input string must match.

The following table describes the properties that you can set in the regex validation configuration object.

Property	Type	Description
`pattern`	string	(Required) A regular expression pattern in ECMAScript regular expression format. The user input text must match the pattern to be valid. The validator supports named captures, which must have the name `<return>`. The validator returns the matched value if the input is valid.
`case_insensitive`	Boolean	(Optional) Set to true if you want to match values case insensitively. The default value is false (case sensitive matching).

For example:

{
   "tasks": [
      ...
   ]
   "validators": [
      {
         "id": "PRODUCT_CODE",
         "regex": {
            "pattern": "PCO-.*"
         }
      }
   ]
}

This validator matches any string that starts with the value PCO-.

Named Entity Recognition Validator

In Named Entity Recognition validation, you specify one or more Named Entity Recognition grammars (and optionally entities) that the user input string must match. This option uses the Answer Server embedded Named Entity Recognition module.

The following table describes the properties that you can set in the eduction validation configuration object.

Property	Type	Description
`grammars`	string	(Required) A comma-separated list of grammars to use to validate the input. You can use Wildcards in the grammar name to specify multiple grammars. However, you cannot use Wildcard values in the directory name. You can specify grammar files with an absolute path or a path relative to the Answer Server working directory.
`entities`	string	(Optional) A comma-separated list of entities in the configured grammars to use to validate the input. You can use Wildcards in the entity string to specify multiple entities.

For example:

{
   "tasks": [
      ...
   ]
   "validators": [
      {
         "id": "UK_PHONE",
         "eduction": {
            "grammars": "configuration/number_phone_gb.xml",
            "entities": "phone/all/gb"
         }
      }
   ]
}

This validator checks that the user input text contains a phone number that matches one of the types in the phone/all/gb entity of the number_phone_gb.xml grammar. If the user input text contains a valid match, the validator returns the normalized match text to the task.

Lua Validator

In Lua validation, you specify the name of a Lua function to use to validate the user input.

The function that you specify must accept a string (the text to validate) as the first parameter. You can optionally also use a taskUtils object as the second parameter, if you want to use taskUtils methods in your validator.

When the text is a valid response, the function must a string (the normalized value to use from the user input text). When the user text is not a valid response the function must either return nil or not return a value.

The following table describes the properties that you can set in the lua validation JSON configuration object.

Property	Type	Description
`function`	string	(Required) The name of the function to call. This function must exist in the Lua script that you configure in your task configuration JSON file (see Lua Processing Scripts).

For example:

{
   "tasks": [
      ...
   ]
   "validators": [
      {
         "id": "FTSE_SYMBOL",
         "lua": {
           "function": "check_ftse_symbol"
         }
      }
   ]
}

This validator calls the check_ftse_symbol function in the task Lua script to validate user input text. If the user input text is valid, the validator sends the value that the function returns to the task.

Process Non-Valid Input

You can configure your response validators to call a Lua function when the user input text fails to validate.

To configure a Lua function, you set the invalid_input_lua property in your validator configuration to the name of the Lua function to call. This function must exist in the Lua script that you configure in your task configuration JSON file (see Lua Processing Scripts).

You can use this function to process non-valid input further. For example, if a user asks a question instead of providing a direct answer to a requirement, you might use the invalid_input_lua function to send the user input text to the Ask action, and retrieve answers from your answer systems.

The function that you specify must take a taskUtils object. If the function sets a response, Answer Server returns this response to the user.

If the function does not update the response, Answer Server uses a default message I'm sorry. I didn't understand that., and then repeats the requirement prompt. You can modify this message, if required (see Default Messages).

For example:

{
   "tasks": [
      {
         "id" : "HOLIDAY",
         "trigger" : {
            "regex" : {
               "pattern" : "(book|go) .* holiday"
            }
         },
         "requirements": [
            {
               "id": "HOLIDAY_LOCATION",
               "prompt": "What country would you like to visit?",
               "validators": [ "COUNTRYVALIDATOR" ] 
            }
         ]
      }
   ],
   "validators": [
      {
         "id": "COUNTRYVALIDATOR",
         "eduction": {
            "grammars": "configuration/place_countries.ecr"
         },
         "invalid_input_lua": "holiday_planner"
      }
   ]
}

If holiday_planner is a Lua function that uses the user input text to send an Ask action, and returns the answer as a prompt, you might get a conversation similar to the following (user text is in italic, Answer Server response in bold):

I'd like to go on holiday.

What country would you like to visit?

What country is Budapest in?

Hungary. What country would you like to visit?

Hungary.

Post-Task Actions

Post-task actions run at the end of the task, after all the task requirements have been satisfied. You can use these options to return an acknowledgment response to the user to confirm the details in the task, and to run a Lua function that performs some final operation with the collected task requirements.

To configure post-task actions, you set the post object in the configuration object for an individual task.

The following table describes the properties that you can set in the post object.

Property	Type	Description
`response`	string	(Optional) A string response to return to the user. For example, this might be a confirmation of the information that was collected in the task. You can include session and task variables, by inserting the variable ID in double curly brackets, for example `{{MYVARIABLE}}`. The variable must already be set in an earlier part of the task (for a task variable) or conversation session (for a session variable). You can optionally use the `task:` or `session:` prefix to specify the type of variable, for example `{{task:MYVARIABLE}}`. If you do not use a prefix, Answer Server searches for the variable in the task variables first, and then the session variables.
`lua`	string	(Optional) A lua function to run at the end of the task, for example to run an external process to complete the task. The function that you specify must accept a `taskUtils` object. See Lua Processing Scripts.
`routing`	object	(Optional) A string or configuration object that determines the task to run next. See Task Routing.

{
   "initial_task" : "GREET",
   "tasks" : [
      {
         "id" : "GREET",
         "pre" : {
            "response" : "Hello and welcome to the Lunch Virtual Assistant."
         },
         "requirements" : [ 
            {
               "id": "USER_NAME",
               "prompt": "Before we get started, could you tell me your name?",
               "scope": "session"
            }
         ],
         "post": {
            "response" : "Welcome, {{USER_NAME}}. How can we help you today?"
         }
      },
      {
         "id" : "LUNCH",
         "pre" : {
            "response" : "I can help you order some lunch."
         },
         "trigger" : {
            "regex" : {
               "pattern" : "(Book|order) .* lunch"
            }
         },
         "requirements" : [ 
            {
               "id" : "FOOD_TYPE",
               "prompt" : "Do you feel like a sandwich or a panini?"
            }, 
            {
               "id" : "FILLING",
               "prompt" : "What filling would you like?"
            }
         ],
         "post" : {
            "response" : "All right, {{USER_NAME}}. We'll get you a {{FILLING}} {{FOOD_TYPE}} right away!",
            "lua" : "send_lunch_order",
            "routing" : "ANYTHING_ELSE"
         }
      }
   ]
}

In this example, the final response in the GREET task uses the session variable {{USER_NAME}}. The final response in the LUNCH task uses the session variable {{USER_NAME}}, and the task variables {{FILLING}} and {{FOOD_TYPE}}.

This simple configuration might result in a conversation like the following example:

Hello and Welcome to the Lunch Virtual Assistant.
Before we get started, could you tell me your name?

Amy

Welcome, Amy. How can we help you today?

I'd like to book lunch.

I can help you order some lunch.
Do you feel like a sandwich or a panini?

Panini

What filling would you like?

Cheese

All right, Amy. We'll get you a Cheese Panini right away!

The task then runs the send_lunch_order Lua function, which might call out to an external system to set up the order. It routes the user to the ANYTHING_ELSE task.

Task Routing

Task routing allows you to specify a task to run after the current task is complete. There are two types of routing that you can use:

Simple. You provide the ID of the task to run after the current task is complete.
Conditional. You specify a set of conditions (such as user selections), and specify the task to run in each case.

To use routing, you set the routing property in the post object of your task (see Post-Task Actions).

####### Configure Simple Routing

In a simple routing, you set the routing property to the ID of the task that you want to run next.

For example:

{
   "initial_task" : "GREET",
   "tasks" : [
      {
         "id" : "GREET",
         "pre" : {
            "response" : "Hello and welcome to the Virtual Assistant. Before we get started, I'd like to ask you a couple of questions."
         },
         "requirements": [ 
            {
               "id": "USER_NAME",
               "prompt": "What is your name?",
               "scope": "session"
            }, 
            {
               "id": "USER_COUNTRY",
               "prompt": "What country do you live in?",
               "scope": "session"
            }
         ],
         "post" : {
               "routing" : "CUSTOMER"
         }
      },
      ...
   ]
}

This example task asks the user for their name and location, and then automatically routes to the CUSTOMER task (which you must also define somewhere in the task configuration file).

####### Configure Conditional Routing

In conditional routing, the routing property contains a configuration object that contains details of the conditional routing.

The following table describes the properties that you can set in the routing configuration object.

Property	Type	Description
`prompt`	string	(Required) A prompt to send to the user to request a choice for routing. You can include session and task variables, by inserting the variable ID in double curly brackets, for example `{{MYVARIABLE}}`. The variable must already be set in an earlier part of the task (for a task variable) or conversation session (for a session variable). You can optionally use the `task:` or `session:` prefix to specify the type of variable, for example `{{task:MYVARIABLE}}`. If you do not use a prefix, Answer Server searches for the variable in the task variables first, and then the session variables.
`map`	array, object	(Required) One or more JSON objects that specify the user responses, and the routing option to use for that response. Each object contains the following properties: * `match` (string). Required. The value that triggers this option. * `routing` (string). Required. The task to route to next when the user response triggers this option. * `response` (string). Optional. A string to return to the user to confirm their option. You can include session and task variables, by inserting the variable ID in double curly brackets, for example `{{MYVARIABLE}}`. The variable must already be set in an earlier part of the task (for a task variable) or conversation session (for a session variable). You can optionally use the `task:` or `session:` prefix to specify the type of variable, for example `{{task:MYVARIABLE}}`. If you do not use a prefix, Answer Server searches for the variable in the task variables first, and then the session variables.
`validation`	array, strings	(Optional) A list of validators to use to validate the user selection. Specify the ID of each validator that you want to use to validate the response to use to route the conversation to a new task. You define the validators separately in the `validators` section of the task configuration JSON file. See Response Validation. If you use validation, you must ensure that all the validators for a `routing` option map back to the value that you specify in your `map` object `match` properties.
`user_cancel`	object	(Optional) An object that defines keywords that a user can use to cancel a task, and the action to perform if they do. For details of the configuration properties, see User Cancellation. The `user_cancel` options in the conditional routing section override any values that you set in the main task configuration or for the individual task.
`system_cancel`	object	(Optional) An object that defines what actions to take when the requirement receives multiple non-valid responses. For details of the configuration properties, see System Cancellation. The `system_cancel` options in the conditional routing section override any values that you set in the main task configuration or for the individual task.

For example:

{
   "tasks" : [
      ...
      {
         "id" : "CUSTOMER",
         "routing" : {
            "prompt" : "Do you have an existing account with us?",
            "validation" : [ "YESNO" ],
            "map" : [
               { 
                  "match" : "yes",
                  "routing" : "EXISTING_DETAILS",
                  "response" : "Okay, {{USER_NAME}}. We'll get you the options for existing customers."
               },
               {
                  "match" : "no",
                  "routing" : "NEW_OPTIONS"
               }
            ]
         }
      }
      ...
   ]
}

This example routes users to different tasks depending on whether they are an existing or new customer.

TIP: When Answer Server returns a routing prompt, it also returns the valid responses (the values of the match property for each object in your map array). You can use these values to present the available options to your users, particularly if you do not want to use validation in your routing object.

####### Use Routing in a Lua Function

When you are using a Lua script in your task configuration, you can route to the next task in your post Lua function.

Answer Server calls the post Lua function at the end of a task, when all the requirements are met. You can use this function to run an external operation, or store data that allows an operative to complete any manual portion of the task.

You can include routing in your post Lua function to control the task that Answer Server occurs next. To do this, you can use the setNextTask method. For more information, refer to the Answer Server Reference.

Task routing in the post Lua response takes precedence over any explicit task routing in the task JSON configuration.

Lua Processing Scripts

You can use Lua functions to perform additional processing for your tasks. For example, if you have a conversation task that sets up the options that a user wants to use to open an account, or make a transaction, you might use a Lua function to call out to an external system to perform the final action.

You can create only one Lua script for your conversation system. You specify the path and file name for this script in the lua_script property in your task configuration JSON file. You can then call out from the configuration for an individual task to a particular function in the script file. For example:

{  
   tasks : [
      ...
   ],
   lua_script : "C:\AnswerServer\Scripts\TaskProcessing.lua",
   validators : [
      ...
   ]
}

You can use a full or relative path. Relative paths can be relative to the Answer Server working directory, or relative to the directory that contains your task configuration JSON file (Answer Server checks for the file relative to the working directory first).

NOTE: You can specify only one Lua script, even if you split your task configuration across multiple JSON files.

In your individual task configurations, you can specify the following properties to set Lua scripts:

The pre object lua property specifies the name of a function to run before the task starts. For example, you can use this function to generate an appropriate preamble to send to the user. See Pre-Task Actions.
The post object lua property specifies the name of a function to run when all the task requirements have been satisfied. You can use this function to run an external process to complete the task. See Post-Task Actions.
The action object lua property (in the user_cancel or system_cancel objects) specifies the name of a function to run when the user or system cancels the task. See Task Cancellation.

All pre, post, and cancel action Lua functions must accept a taskUtils object.

You can also use Lua functions in your validators, to validate user input:

Lua validator configuration objects allow you to specify the name of a Lua function to use to validate user input. Lua validator functions must accept a string (the text to validate) as the first parameter. You can optionally also use a taskUtils object as the second parameter, if you want to use taskUtils methods in your validator. See Response Validation.
The invalid_input_lua property allows you to set the name of a function to run when the user input text does not validate. This function must accept a taskUtils object. See Process Non-Valid Input.

You can use an additional Lua function to determine the message to return to a user and valid responses from the user when their input triggers multiple tasks. The Lua function must accept a routingTable object as the first parameter, which is can use to override the response and options. You can optionally also use a taskUtils object as the second parameter, if you want to use taskUtils methods in your function. See Default Messages.

You can use any of the standard Lua functions and methods in your Lua functions, as well as several custom conversation system Lua methods. The conversation Lua options include simple methods to get and set task and session variables, and a method to forward a question to your other Answer Server systems.

For more information about the Lua functions and methods available, refer to the Answer Server Reference.

Default Tasks

In most cases, you use conversation triggers or routing to direct users to particular conversation tasks. However, you must also configure an initial task and a fallback task.

Initial Task

The initial task runs when the conversation session starts. It activates when you start a conversation by sending the Converse action without the Text parameter (see Start and Continue a Conversation).

The main use of the initial task is to greet your users when they join a conversation session.

To define the initial task, you set the initial_task property in your task configuration JSON to the ID of the task that you want to use. This property is required, and the associated task must exist somewhere in your task configuration file.

For example:

{
   "initial_task" : "GREET",
   "tasks" : [
      {
         "id" : "GREET",
         "pre" : {
            "response" : "Hello and Welcome to the Virtual Assistant. How can I help you?"
         }
      }
   ]
}

Fallback Task

The fallback task runs when there are no existing tasks in the session, for example because all previous tasks are complete.

To define the fallback task, you set the fallback_task property in your task configuration JSON to the ID of the task that you want to use. This property is required, and the associated task must exist somewhere in your task configuration file, even if you have explicit routing such that it is never used.

{
   "fallback_task" : "HELP",
   "tasks" : [
      {
         "id" : "HELP",
         "pre" : {
            "response" : "Is there anything else I can help you with today?"
         }
      }
   ]
}

Default Messages

The conversation system has several default messages that it uses, in addition to the responses that exist in the task configuration. These default messages have standard values in Answer Server. You can change the default values, for example, if you want to run conversations in a different language, use a different conversational style, or customize the messages to your organization.

To configure default messages, you set the default_messages object in your task configuration file. The following sections describe the messages that you can configure.

Response for Non-Valid Input

The non-valid input response is the value that the conversation system returns when the user input was not recognized, for example because the message did not pass validation.

To modify the default message for non-valid input, add the default_messages object and set the invalid_input property to the new message.

For example:

{
   "default_messages" : {
      "invalid_input" : "Je ne comprends pas."
   }
}

The default value for this message is:

I'm sorry. I didn't understand that.

Response for Disambiguation

The disambiguation response is the value that the conversation system returns when there are two or more possible responses. For example, if user text triggers more than one task, or if the task sends a question that has multiple interpretations to a Answer Server Fact Bank system.

To modify the default message for disambiguation, add the ambiguous_input property to the default_messages object. The ambiguous_input property is a configuration object.

The following table describes the properties that you can set in the ambiguous_input object.

Property	Type	Description
`message`	string	(Optional) The message text to display to the user. This message must include the string `[[ITEMS]]`, which is a special token that Answer Server replaces with the disambiguation items. The default value is `"Which of the following did you mean: [[ITEMS]]?"`.
`item_separator`	string	(Optional) The separator to use between the items in the disambiguation list. The default value is `", "` (that is, a comma and a space).
`last_separator`	string	(Optional) The separator to use between the second-last and last item in the list. The default value is `", or "` (that is, a serial comma and or, with appropriate spaces).
`lua`	string	(Optional) A Lua function to call whenever some user input triggers multiple tasks. See Lua Processing Scripts. The Lua function must accept a `routingTable` object as the first parameter, which is can use to override the response and options. You can optionally also use a `taskUtils` object as the second parameter, if you want to use `taskUtils` methods in your function. This function can change the default prompt to return to the user, and the possible responses and tasks that they route to. The function can access the default prompts and options, as well as user input text, session variables, and so on. The function can optionally route to tasks that were not originally triggered. If the function leaves only one possible task, Answer Server routes to that task immediately without prompting the user. If the function removes all possible tasks, Answer Server behaves as if no tasks were triggered. If the function does not modify the prompt or options, Answer Server uses the default options.

For example:

{
   "default_messages" : {
      "ambiguous_input" : { 
         "message": "Which one of [[ITEMS]] did you mean?",
         "item_separator": "/",
         "last_separator": "/"
      }
   }
}

This example results in a disambiguation message of the following form:

Which one of order breakfast/order lunch/order dinner did you mean?

The default configuration gives a disambiguation message of the following form:

Which of the following did you mean: order breakfast, order lunch, or order dinner?

Response for Multiple Answer Disambiguation

The multiple answer disambiguation is the message that the conversation system returns if an Ask action sent as part of the conversation returns multiple possible answers.

This configuration allows you to set different messages depending on the type of answer that is requested. For more information about the types of questions that Answer Server can parse, see The Question Parser Named Entity Recognition Grammar.

To modify the default message for disambiguation, add the multiple_answers_disambiguation property to the default_messages object. The multiple_answers_disambiguation property is a configuration object.

The following table describes the properties that you can set in the multiple_answers_disambiguation object.

Property	Type	Description
`entity`	object	(Optional) An object that describes the message to display when a question about a particular entity returned multiple answers. This object can contain the following properties: * `message` (string). Optional. The message text to display to the user. This message must include the string `[[ITEMS]]`, which is a special token that Answer Server replaces with the disambiguation items. It can also include the string `[[ENTITY]]`, which is a special token that Answer Server replaces with the name of the entity in the question. The default value is `"Found multiple possibilities for '[[ENTITY]]', which did you mean: [[ITEMS]]?"`. * `item_separator` (string). Optional. The separator to use between the items in the disambiguation list. The default value is `", "` (that is, a comma and a space). * `last_separator` (string). Optional. The separator to use between the second-last and last item in the list. The default value is `", or "` (that is, a serial comma and or, with appropriate spaces).
`qualifier_code`	object	(Optional) An object that describes the message to display when a question returned multiple answers with different qualifiers that you can use to determine the correct answer to use. This object can contain the following properties: * `message` (string). Optional. The message text to display to the user. This message must include the string `[[ITEMS]]`, which is a special token that Answer Server replaces with the disambiguation items. The default value is `"Got multiple answers. Choose a qualifier to disambiguate on: [[ITEMS]]?"`. * `item_separator` (string). Optional. The separator to use between the items in the disambiguation list. The default value is `", "` (that is, a comma and a space). * `last_separator` (string). Optional. The separator to use between the second-last and last item in the list. The default value is `", or "` (that is, a serial comma and or, with appropriate spaces).
`qualifier_value`	object	(Optional) An object that describes the message to display when a question returned multiple answers with different qualifiers that you can use to determine the correct answer to use. This object can contain the following properties: * `message` (string). Optional. The message text to display to the user. This message must include the string `[[ITEMS]]`, which is a special token that Answer Server replaces with the disambiguation items. The default value is `"Which value did you want to filter by: [[ITEMS]]?"`. * `item_separator` (string). Optional. The separator to use between the items in the disambiguation list. The default value is `", "` (that is, a comma and a space). * `last_separator` (string). Optional. The separator to use between the second-last and last item in the list. The default value is `", or "` (that is, a serial comma and or, with appropriate spaces).
`additional_choices`	object	(Optional) An object that describes additional messages to return . This object can contain the following properties: * `all_answers` (string). Optional. The message text to display to allow the user to choose to return all available answers. The default value is `Return all answers`. * `reject_answers` (string). Optional. The message text to display to allow the user to choose to reject all available answers. The default value is `None of these`.
`rejected_answers`	object	(Optional) An object that describes the message to display when the user rejects the available answers. This object can contain the following properties: * `message` (string). Optional. The message text to display to the user. The default value is `I'm sorry, I don't have an answer for that."`.

For example:

"default_messages": {
   "multiple_answers_disambiguation": {
      "entity": {
         "message": "I found several possible matches for '[[ENTITY]]'. Which of the following matches your intent: [[ITEMS]]?"
      },
      "qualifier_code": {
         "message": "I found multiple answers for that. Pick one of these qualifiers to clarify your original question: [[ITEMS]]"
      },
      "qualifier_value": {
         "message": "I have several answers for you, but I need more information to give you the best one. Choose one of the following values: [[ITEMS]]"
      },
      "additional_choices": {
         "all_answers": "I want it all",
         "reject_answers": "That's not helpful"
      },
      "rejected_answers": {
         "message": "Then I'm afraid I can't help you with your question, because I have no further information."
      }
   }
}

TIP: When the Converse action calls out to the Ask action to ask a question, Answer Server returns the possible answers in the Converse action response, along with the disambiguation information. At this point, you can use the special string ANSWER_NUMBER_N in the Text parameter of the Converse action to return a particular answer from the list, where N is the number of the answer (starting from 0).

Task Cancellation

You can configure settings to define when and how to cancel a conversation task.

You can define task cancellation options at the top level of your task configuration file, to define global cancellation options. You can also define it in a task, a task requirement, and in a post-task conditional routing object. Values that you set in the requirement or routing objects override the settings at the task level, which override the global values.

User Cancellation

The user_cancel property defines settings that allows users to cancel a conversation task, and what actions to take.

The following table describes the options that you can set in the user_cancel object.

Property	Type	Description
`keywords`	array, strings	(Optional) A list of keywords that the user can type to cancel the task. When a user provides one of these keywords, Answer Server cancels the current conversation task, and runs the specified `action`. The default value is cancel. You can turn off user cancellation by setting keywords to an empty array. NOTE: Answer Server checks for cancellation terms before it performs response validation, so it cancels the task even if the cancellation keyword is also a valid response to the task requirement. OpenText recommends that you choose your response validation and cancellation keywords carefully to avoid a conflict. You can override global or task-level cancellation keywords by setting keywords in a requirement (or by setting the requirement keywords to an empty array).
`case_insensitive`	Boolean	(Optional) Set to false if you want to match the specified keywords case sensitively. The default value is true (not case sensitive).
`action`	object	(Optional) An object that defines the action to perform when the user cancels the task. You can set the following properties: * `response` (string) Optional. The response to return when the task is canceled. You can include session and task variables. The default value is Task canceled. * `routing` (string) Optional. The ID of the task to route to when the task is canceled. The default value is the configured `fallback_task` (see Default Tasks). * `lua` (string) Optional. The name of a Lua function to run when the task is canceled. See Lua Processing Scripts. You can set this property to `null` to remove a Lua script that you configured at a more general level.

For example:

{  
   "user_cancel" : {
      "keywords" : [ "cancel", "end", "stop" ],
      "action" : {
         "response" : "Okay {{USER_NAME}}, we'll cancel that for now.",
         "routing" : "HELP" 
      }
   }
}

System Cancellation

The system_cancel property defines settings that define what actions to take when the conversation task receives multiple non-valid responses.

NOTE: Any requirements that have ask_options configured ignore any system cancellation because in this case, Answer Server treats all non-valid responses as potential questions.

The following table describes the options that you can set in the system_cancel object.

Property	Type	Description
`max_attempts`	number	(Optional) The number of non-valid input attempts that the user can make before the system cancels the task. The default value is 0 (no limit).
`action`	object	(Optional) An object that defines the action to perform when the system cancels the task after non-valid input. You can set the following properties: * `response` (string) Optional. The response to return when the task is canceled. You can include session and task variables. The default value is Task aborted. * `routing` (string) Optional. The ID of the task to route to when the task is canceled. The default value is the configured `fallback_task` (see Default Tasks). * `lua` (string) Optional. The name of a Lua function to run when the task is canceled. See Lua Processing Scripts. You can set this property to `null` to remove a Lua script that you configured at a more general level.

For example:

{  
   "system_cancel" : {
      "max_attempts" : 5,
      "action" : {
         "response" : "I'm sorry, I still didn't understand that. Would you like to try again?",
         "lua" : "system_cancel"
      }
   }
}

Task Configuration Example

The Answer Server installation includes an example conversation JSON configuration and Lua script.

You can view the example files in the conversation/examples/travel directory in your Answer Server installation. The default Answer Server configuration file contains a commented example conversation system configuration, which you can uncomment to run the example.

Configure the Conversation Agentstore

NOTE: The Conversation Agentstore is an optional component. You do not need to configure it if you do not want to use agent triggers in your conversation tasks. See Conversation Triggers.

The Agentstore component is a specially configured Content component.

In agent search, you send plain text or a document to the Agentstore, which returns any agents that match the document. In a Conversation system, you can store conversation triggers in the Agentstore.

The conversation task can query the Agentstore to find any conversation triggers that match the text that a user provides.

Configure the Agentstore Component

The Answer Server package includes a predefined Conversation Agentstore configuration file.

NOTE: OpenText recommends that you use a separate Agentstore for Passage Extractor, Answer Bank, and Conversation answer systems.

To configure the Agentstore component for your Conversation system

In your Answer Server installation directory, copy the Agentstore agentstore.cfg configuration file.
Open your Agentstore installation directory.
Paste the Answer Server Agentstore configuration file. Overwrite the installed configuration file (you might want to make a copy of it first).
Open the configuration file in a text editor.
Update the [License] section with the host and port information for your License Server. For more information, see Configure the License Server Host and Port.
In the [Server] section, find the Port parameter. Check that the specified port is available on the host machine, or change it to an available port.

NOTE: If you modify the port, make sure to update the system configuration in your Answer Server configuration file. See Configure the Conversation System.
In the [Service] section, find the ServicePort parameter. Check that the specified port is available on the host machine, or change it to an available port.
Save and close the configuration file.

Configure the Conversation System to Use Agentstore

To use Agent triggers, you must include the Agentstore details in your conversation system configuration by setting the AgentstoreHost and AgentstoreACIPort configuration parameters. Depending on your system configuration, you might also need to set AgentstoreSSLConfig and AgentstoreGSSServiceName.

[MyConversation]
Type=Conversation
TaskConfigurationFile=C:\AnswerServer\Conversation\tasks.json
// Trigger Agentstore
AgentStoreHost=localhost
AgentStoreAciport=5002

Index Conversation Trigger Agents

After you have configured the Agentstore, you must index the conversation trigger agents that the Conversation system must use.

To do this, you must create the IDX or XML files that contain your conversation triggers (see Agent Triggers). You can then use a DREADD index action to add the IDX or XML files to your Agentstore. For example:

http://localhost:5001/DREADD?C:\AnswerServer\conversation\conversation_triggers.idx.gz

Check Spelling in Conversations

Answer Server can check the spelling of input to a conversation system. This means that if a user makes a spelling error, the conversation system can still suggest potential answers.

When a user submits input that does not trigger any tasks, Answer Server runs the spelling checker. If a spelling correction is possible and that correction would trigger one or more tasks, the user is presented with the suggested correction and a list of matching tasks through the standard disambiguation prompt.

To check spelling you must have an Content component that contains a large amount of indexed documents. The words in the conversation are checked against the words present in the index. With a sufficiently large amount of data spelling errors can be identified.

To check spelling in conversations

Open your configuration file in a text editor.

Create a new section in the configuration file and configure a spelling checker. You can give the section any name. Set the following parameters:


Type	The type of component to use to check spelling. Set this parameter to `Content`.
Host	The host name or IP address of the machine hosting the Content component.
ACIPort	The ACI port of the Content component.
LanguageType	The value to use for the `LanguageType` parameter, in `Query` actions sent to the Content component.

For example:

[MySpellingChecker]
Type=Content
Host=localhost
ACIPort=12345
LanguageType=englishUTF8

Find the configuration section for the Conversation system. In this section, set the configuration parameter SpellcheckEngine to the name of the section that you created in the previous step. For example:
```
[MyConversationSystem]  
SpellcheckEngine=MySpellingChecker
```
Restart Answer Server for your configuration changes to take effect.

Hold Conversations in Answer Server

This section describes how to hold conversations in Answer Server.

Hold a Conversation

To start conversations, you must create a conversation session in Answer Server, which generates a session token. You use this session token to track a particular conversation in the Converse action.

Create a Conversation Session

To create a conversation session, you use a ManageResources action in a POST request method, with the details of the operation to perform provided in the Data parameter as a JSON object.

Action=ManageResources&SystemName=MyConversations
data={
   "operation":"add",
   "type":"conversation_session"
}

You can optionally pass session variables to the conversation session, so that the conversation does not have to ask for information that is already available in your system. For example, you might pass in the user name from the login that the user provided when they signed into your application. For example:

Action=ManageResources&SystemName=MyConversations
data={
   "operation":"add",
   "type":"conversation_session",
   "session_variables": [
      {"name": "USER_NAME", "value": "Jane"},
      {"name": "COUNTRY", "value": "USA"}
   ]			
}

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

This action returns a session token, which you can use in the Converse action.

Retrieve Active Conversation Sessions

To retrieve the session IDs of your active conversation sessions, you use a GetResources action, with Type set to conversation_session. For example:

action=GetResources&SystemName=MyConversations&Type=conversation_session

Start and Continue a Conversation

To run conversations, you use the Converse action. You must set SystemName to the name of the conversation system, and SessionID to the session token that you receive from the ManageResources action when you create the session.

For example:

action=Converse&SystemName=MyConversations&SessionID=860028728520387723

This example starts the conversation without providing any user text. In this case, Answer Server runs the conversation task that you have configured as your initial task and returns the response from that task. See Initial Task.

To provide user text, you add the Text parameter:

action=Converse&SystemName=MyConversations&SessionID=860028728520387723&Text=I would like to buy some shares

Each action with the same session ID carries on the conversation, running the appropriate conversation tasks. You provide each new user text selection in the Text parameter, and the action returns the response from the conversation task.

When the Converse action calls out to the Ask action to ask a question, the Ask response can include additional information to allow the user to disambiguate between multiple possible answers. In this case, Answer Server returns the possible answers in the Converse action response, along with the disambiguation information. At this point, you can use the special string ANSWER_NUMBER_N to return a particular answer from the list, where N is the number of the answer (starting from 0).

You can retrieve the XML Schema Definitions (XSDs) for the Converse action by using the GetResources action with the Type parameter set to XSD. For more information, refer to the Answer Server Reference.

Close a Conversation Session

At the end of a conversation, you can delete the conversation session to free up the session license. To delete the conversation session, you use another ManageResources action, with the delete operation and the appropriate session ID. For example:

Action=ManageResources&SystemName=MyConversations
data={
   "operation":"delete",
   "type":"conversation_session",
   "ids":["860028728520387723"]
}

TIP: You can configure Answer Server to automatically close inactive conversation sessions, by setting the SessionExpirationInterval and SessionExpirationIdleTime configuration parameters in the system configuration section. For more information, see Configure the Conversation System, and Conversation System Configuration Parameters.

Retrieve a Conversation Transcript

You can retrieve a full transcript of a particular conversation session by using the GetResources action with Type set to Transcript, and IDs set to the ID of the conversation session that you want to retrieve. For example:

action=GetResources&Type=Transcript&SessionID=860028728520387723

TIP: You can also use the transcript in your conversation Lua scripts. See Lua Processing Scripts and Conversation System Configuration Parameters.

Use Natural Language Generation in Answer Server

This section describes how to configure Answer Server to use natural language generation (NLG), and how to use the NLG action to generate sentences.

Configure Natural Language Generation

Answer Server Natural Language Generation (NLG) generates a user-friendly natural language sentence from a JSON object that describes the parts of speech to include. You can use NLG, for example, to generate user-friendly responses for a user interface in a programmatic way.

NOTE: You can use NLG only if your license permits it.

Answer Server uses the SimpleNLG-4.4.8.jar file to perform natural language generation. You must enable NLG and provide the location of this

To configure Answer Server to use NLG

Open your configuration file in a text editor.
Create the [NLG] configuration section.
In the [NLG] section, set Enabled to True.
Set JarPath to the path to the directory that contains the SimpleNLG-4.4.8.jar file. This file is available in your Answer Server installation.
Save and close the configuration file.

NOTE: If you enable NLG and your license does not allow it, or Answer Server cannot find the SimpleNLG-4.4.8.jar in the specified directory, Answer Server does not start.

Run Natural Language Generation

You run NLG by sending the NLG action to Answer Server in a POST request method. You submit a JSON object, which contains details of the parts of speech that you want to use to generate a sentence, and the action returns the appropriate sentence.

curl http://localhost:12000/?action=NLG –F Spec={
  "sentences": [
    {
      "subject": {
        "noun_phrases": [
          { "value": "the dog" }, 
          { "value": "your giraffe" }
        ]
      },
      "verb": {
        "verb_phrase": {
          "value": "chase",
          "modifiers": [ "quickly" ]
        }
      },
      "object": {
        "noun_phrases": [
          { "value": "the monkey" },
          { "value": "George" },
          { "value": "Martha" }
        ],
        "conjunction": "or"
      }
    }
  ]
}

This action generates the following sentence:

The dog and your giraffe quickly chase the monkey, George or Martha.

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

Appendixes

This section contains additional information about Answer Server.

Debug Your Conversation Lua Scripts

Debug Your Conversation Lua Scripts

The Answer Server installation includes IDE files to allow you to debug your Conversation system Lua scripts with the ZeroBrane Studio Lua IDE on Windows. For more information about conversation Lua scripts, see Lua Processing Scripts.

To use Lua debugging, you must install ZeroBrane Studio (see https://studio.zerobrane.com).

After you install ZeroBrane Studio, you must:

Copy the files from the lua_ide_files directory in your Answer Server installation to the ZeroBrane Studio installation directory, merging with the files that are already there,
Copy the following files from the lua directory in your Answer Server installation to a debugging project directory (which can be anywhere):
- autn_conversation.dll A DLL for debugging conversation Lua scripts.
- taskutils_factory.lua A helper module for constructing taskUtils objects.
- autn_conversation.cfg A copy of the answerserver.cfg to use during debugging.

You can then create a debug script to allow you to debug individual Lua functions. The Lua debug script file must have the following code at the start, where LuaScript.lua is your conversation Lua script file:

require("autn_lua_conversation").as_global() -- load lua functions into global namespace
local factory = require("taskutils_factory") -- load factory module
require("LuaScript.lua") -- load the file that contains Lua scripts to debug

The rest of the debug script can call individual functions in your LuaScript.lua, set breakpoints and check the output.

For functions that require a taskUtils object, you can use the factory.create_taskutils helper function provided in the taskutils_factory.lua helper module. This helper module also lets you specify various input and output parameters, such as tables containing session and task variables, and tables for storing the result of API calls such as setNextTask. For more information, see the documentation in taskutils_factory.lua.

NOTE: When you debug ask operations in your Lua scripts, the script sets up all the systems in your configuration file, but any required Knowledge Discovery components and Fact Bank databases must be available.

To debug Named Entity Recognition validators, you must supply a License Server license key file that contains a license for Answer Server. Set the EductionLicenseFile parameter to the path to your license key in the conversation system configuration section of your debugging configuration file. For example:

[MyConversation]  
EductionLicenseFile=C:\KnowledgeDiscovery\licensekey.dat

Answer Server Help

Filter:

All Files

Submit Search

The OpenText Answer Server Reference contains information about the actions and configuration parameters that you can use with Answer Server. The Reference includes the following sections.


Actions	Describes the actions you can send to Answer Server. Actions allow you to query Answer Server and to instruct it to perform a variety of operations.
Configuration Parameters	Describes the parameters that determine how the Answer Server operates. Configuration parameters are set in the Answer Server configuration file.
Service Actions	Describes service actions, which return data about the Answer Server service and allow you to control Answer Server.

Actions

This section describes the actions that you can use with Answer Server.

Introduction to Actions

Actions allow you to query an ACI server and instruct it to perform a variety of operations.

NOTE: All actions must be sent to the server Port. The configured authorization roles determine which users can send which actions to the port. See Authorization Roles Configuration Parameters.

The general syntax of these actions is:

http://host:port/action=action&requiredParams&optionalParams

where,


`host`	is the IP address or name of the machine on which the ACI server is installed.
`port`	is the ACI port by which actions are sent to the ACI server (set by the `Port` parameter in the `[Server]` section of the configuration file).
`action`	is the name of the action you want to run.
`requiredParams`	are the parameters you must supply for the action you are requesting. (Not all actions have required parameters.)
`optionalParams`	are parameters you can supply for the action you are requesting. (Not all actions have optional parameters.)

Separate the individual parameters with an ampersand (&). Separate parameter names from values with an equals sign (=). You must percent-encode all parameter values.

Ask Actions


Ask	Sends a question to Answer Server and retrieves an answer.
Converse	Starts or continues a conversation.

Ask

Sends a question to Answer Server and returns appropriate answers.

You specify the question in plain text in the Text parameter.

Answer Server parses the question, and attempts to retrieve associated answers from all your configured answer systems (fact banks, answer banks, passage extractors, and RAG). If you have multiple systems configured, Answer Server finds any available answers in all of them. You can optionally set the SystemNames parameter to specify the configured systems to attempt to retrieve answers from.

TIP: When the system forwards actions to another Knowledge Discovery component, such as the answer bank Agentstore or the passage extractor Content component, you can use the AllowedQueryParameters configuration parameter to specify parameters that Answer Server must pass through to the other components. You can then add these parameters to your Ask action to improve your query and results.

For passage extractor and RAG systems, you can also use the CandidateRetrievalDefaults configuration parameter to set parameters that Answer Server must add to the query to the Content component index to retrieve candidate documents.

Example

http://12.3.4.56:12000/action=Ask&Text=What is the largest city in Norway?

This action requests an answer to the question What is the largest city in Norway.

Required Parameters

The following action parameters are required.

Parameter	Description
Text	The plain text question that you want to answer.

Optional Parameters

This action accepts the following optional parameters.

Parameter	Description
Context	A question context ID to use to limit the scope of the question.
CustomizationData	A JSON object that specifies additional information to use in the query.
FirstResult	The number of the first result to return.
MaxResults	The maximum number of answers to return.
MinScore	The minimum score that an answer can have
Sort	The method to use to sort the answers.
SystemNames	The systems and system groups that you want to request answers from.
Timeout	The maximum length of time to process the action for.
TotalResults	Whether to return the total number of available answers.

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

Response

You can retrieve the full response XSD by sending the GetResources action with Type set to XSD.

Converse

Starts or continues a conversation with a user, using an existing session token.

The Converse action requires the SystemName of your configured conversation system, and a SessionID (session token) for your conversation. You create the session token by using the ManageResources action. You can retrieve the IDs of existing conversation sessions by sending the GetResources action with Type set to conversation_session.

When you want to start a conversation, you can send Converse with only the SystemName and SessionID parameters. In this case, Answer Server runs the conversation task that has the initial state trigger (for example, a default greeting). If you do not have a configured task with the initial state trigger, Answer Server runs the conversation task that has the empty state trigger.

For more information about task triggers, refer to the Answer Server Administration Guide.

After the start of the conversation, you provide user text in the Text parameter. Answer Server processes the user text according to your task configuration, running the appropriate conversation tasks. The action response includes the result of the current task action, which might be a text reply, a request for information, or an acknowledgment, depending on your task configuration.

You continue the conversation by sending further Converse actions with the same SessionID.

Example

http://12.3.4.56:12000/action=Converse&SystemName=MyConversation&SessionID=860028728520387723

This action starts a conversation with session ID 860028728520387723 (previously created by using ManageResources).

Required Parameters

The following action parameters are required.

Parameter	Description
SessionID	The session token for the conversation session.
SystemName	The system that you want to use to converse with the user.

Optional Parameters

This action accepts the following optional parameters.

Parameter	Description
Text	The text that the user supplies.

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

Response

You can retrieve the full response XSD by sending the GetResources action with Type set to XSD.

Report

Returns all facts about a particular entity.

This action applies only to Fact Bank systems with an ODBC backend.

You provide an entity, and Answer Server returns all facts in your Fact Bank systems where this entity is the entity, or a property or qualifier value. You can optionally specify a particular set of systems by setting SystemNames. You can also use other Ask action parameters to restrict the results.

Example

http://12.3.4.56:12000/action=Report&Entity=Cambridge

This action requests all facts where Cambridge is the entity, or where it appears as a property or qualifier value.

Required Parameters

The following action parameters are required.

Parameter	Description
Entity	The entity for which you want to retrieve facts.

Optional Parameters

This action accepts the following optional parameters.

Parameter	Description
Context	A question context ID to use to limit the scope of the result.
CustomizationData	A JSON object that specifies additional information to use in the query.
FirstResult	The number of the first result to return.
MaxResults	The maximum number of results to return.
SystemNames	The systems and system groups that you want to request results from.
Timeout	The maximum length of time to process the action for.
TotalResults	Whether to return the total number of available results.

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

Response

You can retrieve the full response XSD by sending the GetResources action with Type set to XSD.

General Actions


Admin	Opens the Knowledge Discovery Admin interface.
DiskReport	Displays a report of disk usage of a component.
Encrypted	Sends an encrypted action.
GetChildren	Displays details of child components.
GetLicenseInfo	Displays license information.
GetVersion	Displays version information.
GRL	Displays the request log.
MemoryReport	Displays memory usage.
Schedule	Schedules an action to run automatically on a defined schedule.
ShowPermissions	Displays permissions for an IP address.
SystemLimits	Displays limits for the system on which the server is installed.
ThreadStatus	Displays a list of ACI threads and what each thread is doing.

Admin

Opens the Knowledge Discovery Admin interface. This interface allows you to view data for the component and provides some administrative actions.

To use this action, you must have an admin.dat file available for the component. You can configure the location of this file by using the AdminFile configuration parameter in the [Paths] section.

Example

http://12.3.4.56:6010/action=Admin

This action accesses the Knowledge Discovery Admin interface for the component located on a machine with the IP address 12.3.4.56 that uses port 6010.

DiskReport

Returns a report of the disk usage.

NOTE: This is an administrative action that can be sent only by users that belong to an authorization role that allows the Admin standard role, or which enables the action explicitly. See Authorization Roles Configuration Parameters.

Example

http://12.3.4.56:9010/action=DiskReport

This action requests a disk report from Answer Server.

Optional Parameters

This action accepts the following optional parameters.

Parameter	Description
MaxDepth	The number of levels of directories and files to print in the output.

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

Encrypted

Send encrypted actions. When you are encrypting actions, encrypt the action and then send the Encrypted action, with the encrypted data for the original action in the Data parameter.

NOTE: The Encrypted action is for OEM encryption only. For non-OEM environments, OpenText recommends that you configure Secure Socket Layer (SSL) connections between ACI servers and applications. For more information, see Secure Socket Layer Parameters.

Example

http://12.3.4.56:9000/action=Encrypted&Data=MzJ8kLiGY7QBrEwSDTdeOduOLlBhABllsJRmu8RDCKGG%2BZY%3D

This action sends an encrypted action.

Required Parameters

The following action parameters are required.

Parameter	Description
Data	The encrypted query.

Optional Parameters

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

GetChildren

Displays details of the child components for Answer Server.

Example

http://12.3.4.56:9000/action=GetChildren

This action requests child component information from a component.

Optional Parameters

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

GetLicenseInfo

Displays licensing information for actions.

Example

http://12.3.4.56:9000/action=GetLicenseInfo

This action requests action license information from a component.

Optional Parameters

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

GetVersion

Displays details of the version and build of an ACI server, the directory it runs on, and server time.

Example

http://12.3.4.56:9000/action=GetVersion

This action requests version details from a component.

Optional Parameters

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

GRL

Displays a log of requests, including the date and time that a request was made, the client IP address that made the request, and the internal thread that handled the action. The list displays only the first 1000 characters of each request.

Example

http://12.3.4.56:9000/action=GRL

This action gets the request log from an ACI server.

Optional Parameters

This action accepts the following optional parameters.

Parameter	Description
Format	The format to return the log in.
OpenLinks	Whether to open links in a new window.
Refresh	The interval in which to refresh the log.
Tail	The number of requests to display.

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

MemoryReport

Details memory usage.

Example

http://12.3.4.56:9000/action=MemoryReport

This action requests memory usage details from a component.

Optional Parameters

This action accepts the following optional parameters.

Parameter	Description
MaxDepth	The maximum depth to return memory information for.

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

Schedule

The Schedule action configures Answer Server to run an action automatically on a defined schedule, and is used to manage schedules.

The schedules you define are saved so that they continue to run after the server is restarted. If the server is offline when an action is due to begin, the action is skipped and does not run until the start time for the next cycle.

Type: Synchronous

Parameter	Description	Required
`ScheduleAction`	The action to perform: * `add` - add a new schedule. * `addHoliday` - prevent actions being started by a named schedule for a specified time period. * `cancel` - cancel (delete) a schedule. * `cancelHoliday` - cancel a holiday created with `ScheduleAction=addHoliday`. * `clear` - clear (delete) all schedules. * `list` - list schedules. * `pause` - pause a schedule. Actions do not run when a schedule is paused. * `resume` - resume a schedule that was paused. * `update` - update an existing schedule.	Yes
`Name`	The name of the schedule. Names are case-sensitive and cannot begin with an underscore.	Required unless `ScheduleAction` is `clear` or `list`.

When you set ScheduleAction=add or ScheduleAction=update, use the following parameters to define the schedule:

Parameter	Description	Required
`_action`	The name of the action to schedule.	Required to add a schedule.
`_parameter`	A parameter to pass to the scheduled action each time it runs (replace `parameter` with the actual parameter name).	No
`AllowParallel`	A Boolean value that specifies whether to run the scheduled action if the previous occurrence is still running or queued. This parameter has a default value of `false` for new schedules.	No
`Cycles`	The maximum number of times to run the action. If you do not set this parameter when adding a new schedule, there is no limit on how many times the action can run.	No
`End`	The date and time at which to end the schedule. Specify the value in the format `YYYY-SHORTMONTH-DD HH:NN:SS`. If you do not set this parameter when adding a new schedule, the schedule runs indefinitely.	No
`Intervals`	A comma-separated list of time durations, to specify how long the server waits before running the action again. If the number of `cycles` exceeds the number of `intervals`, the server returns to the start of the list. The default interval for new schedules is 24 hours. The units you can use for setting time durations are: `years`, `months`, `weeks`, `days`, `hours`, `minutes`, and `seconds`. Each unit can be abbreviated to its first letter, for example `3h` instead of `3hours`. Months abbreviates to `m` and minutes to `n`.	No
`Start`	The date and time at which to start the schedule. Specify the value in the format `YYYY-SHORTMONTH-DD HH:NN:SS`. If you do not set this parameter when adding a new schedule, the schedule starts immediately.	Required when updating the `intervals` for a schedule.

When you set ScheduleAction=addHoliday or ScheduleAction=cancelHoliday, use the following parameters to define the holiday:

Parameter	Description	Required
`End`	The date and time at which to end the holiday. Specify the value in the format `YYYY-SHORTMONTH-DD HH:NN:SS`.	Required when `ScheduleAction` is `addHoliday` or `cancelHoliday`.
`Start`	The date and time at which to start the holiday. Specify the value in the format `YYYY-SHORTMONTH-DD HH:NN:SS`.

Examples

The following example runs the BackupServer action at midday on weekdays, starting on Monday 27th January 2020, for 10 weeks:

/action=schedule&scheduleaction=add
                &name=WeekdayBackups
                &start=2020-JAN-27 12:00:00
                &intervals=24h, 24h, 24h, 24h, 72h
                &cycles=50
                &_action=BackupServer
                &_path=./backups/

The following action specifies that the schedule should not run any actions between the specified times:

/action=schedule&scheduleaction=addHoliday
                &name=WeekdayBackups
                &start=2020-FEB-03 11:00:00
                &end=2020-FEB-07 13:00:00

The following example lists schedules that you have defined:

/action=schedule&scheduleaction=list

The following example updates the number of cycles in the WeekdayBackups schedule:

/action=schedule&scheduleaction=update
                &name=WeekdayBackups
                &cycles=100

The following example removes the WeekdayBackups schedule:

/action=schedule&scheduleaction=cancel
                &name=WeekdayBackups

The following example removes all schedules:

/action=schedule&scheduleaction=clear

Response

The following is an example response from /action=schedule&scheduleaction=list

<autnresponse xmlns:autn="http://schemas.autonomy.com/aci/">
  <action>SCHEDULE</action>
  <response>SUCCESS</response>
  <responsedata>
    <schedule>
      <name>WeekdayBackups</name>
      <action>
        <name>backupserver</name>
        <parameter name="path">./backups</parameter>
        <parameter name="scheduledTask">true</parameter>
      </action>
      <holiday>
        <start>2020-Feb-03 11:00:00</start>
        <end>2020-Feb-07 13:00:00</end>
      </holiday>
      <start>2020-Jan-27 12:00:00</start>
      <intervals>1 day, 1 day, 1 day, 1 day, 3 days</intervals>
      <cycles>50</cycles>
      <cyclesRun>2</cyclesRun>
      <cyclesSkipped>1</cyclesSkipped>
      <allowParallel>true</allowParallel>
      <paused>true</paused>
    </schedule>
  </responsedata>
</autnresponse>

One or more holiday elements might be present if you define holiday periods using scheduleaction=addholiday.
The cyclesRun element describes the number of times the scheduled action has run and only appears if the value is greater than zero.
The cyclesSkipped element describes the number of times the scheduled action has been skipped. Actions can be skipped when the server is down or when you schedule a holiday period. This element only appears if the value is greater than zero.
The allowParallel element specifies whether a scheduled action occurs if the previous occurrence is still running or queued, and only appears if the value is true.
The paused element indicates whether the schedule is paused and only appears if the value is true.

ShowPermissions

The ShowPermissions action returns information on whether a specified IP address is allowed to send query actions or administrative actions to the action port.

For users that belong to the Admin standard role (see Authorization Roles Configuration Parameters), the ShowPermissions response also includes information about the rules that are used to define whether a particular client IP address has particular permissions.

Example

action=ShowPermissions&IP=12.3.4.56

This action checks whether the machine with the IP address 12.3.4.56 is allowed to send actions to the port. If you send the action as a user that belongs to the Admin standard role, the action returns the following information:

  <?xml version="1.0" encoding="UTF-8" ?>  
- <autnresponse xmlns:autn="http://schemas.autonomy.com/aci/">
     <action>SHOWPERMISSIONS</action>
     <response>SUCCESS</response>
   - <responsedata>
    - <autn:rules>
      - <autn:queryclient>
          <autn:enabled>true</autn:enabled>
          <autn:origin>*</autn:origin>
        </autn:queryclient>
      - <autn:adminclient>
          <autn:enabled>true</autn:enabled>
          <autn:origin>*</autn:origin>
        </autn:adminclient>
      - <autn:allowedproxy>
          <autn:enabled>true</autn:enabled>
          <autn:origin>12.3.4.56</autn:origin>
          <autn:origin>::1</autn:origin>
          <autn:origin>127.0.0.1</autn:origin>
        </autn:allowedproxy>
      - <autn:servicestatusclient>
          <autn:enabled>true</autn:enabled>
          <autn:origin>*</autn:origin>
        </autn:servicestatusclient>
      - <autn:servicecontrolclient>
          <autn:enabled>true</autn:enabled>
          <autn:origin>*</autn:origin>
        </autn:servicecontrolclient>
      - <autn:indexclient>
          <autn:enabled>true</autn:enabled>
          <autn:origin>::1</autn:origin>
          <autn:origin>127.0.0.1</autn:origin>
        </autn:indexclient>
      - <autn:allowedindexproxy>
          <autn:enabled>true</autn:enabled>
          <autn:origin>12.3.4.56</autn:origin>
          <autn:origin>::1</autn:origin>
          <autn:origin>127.0.0.1</autn:origin>
        </autn:allowedindexproxy>
      </autn:rules>
    - <autn:requested>
        <autn:ip>12.3.4.56</autn:ip>
        <autn:ipvalid>true</autn:ipvalid>
        <autn:queryclient>true</autn:queryclient> 
        <autn:adminclient>true</autn:adminclient>
        <autn:allowedproxy>true</autn:allowedproxy>
        <autn:servicestatusclient>true</autn:servicestatusclient>
        <autn:servicecontrolclient>true</autn:servicecontrolclient>
        <autn:indexclient>false</autn:indexclient>
        <autn:allowedindexproxy>true</autn:allowedindexproxy>
        <autn:cors>
           <autn:enabled>true</autn:enabled>
           <autn:origin>*</autn:origin>
        </autn:cors>
      </autn:requested>
     </responsedata>
  </autnresponse>

If you send the action as a user that does not belong to the Admin role, the action does not return the <autn:rules> section of the response.

Alternatively you can specify the action without an IP address, in which case Answer Server returns the permissions information for the referring IP address.

Optional Parameters

This action accepts the following optional parameters.

Parameter	Description
IP	the IP address (in numeric format) that you want to show permissions for.

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

SystemLimits

Returns details of the following system limits:

maximum core file size (in bytes) - UNIX platforms only
maximum file size (in bytes) - UNIX platforms only
maximum map count - UNIX platforms only
block size (in bytes)
maximum number of open file handles
the number of processors

On Microsoft Windows operating systems, the action returns a value of -1 for the limits in this list that are marked as UNIX platforms only. For these items, a value of -1 on a UNIX platform means that the item is unlimited.

Example

http://12.3.4.56:9010/action=SystemLimits

This action requests the system limits from Answer Server.

Optional Parameters

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

ThreadStatus

Displays a list of all ACI threads and specifies what each thread is doing.

Example

http://12.3.4.56:9000/action=ThreadStatus

This action uses port 9000 to request thread information from a component, which is located on a machine with the IP address 12.3.4.56.

Optional Parameters

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

Management Actions


GetJobStatus	Retrieves the status of a ManageResources update action.
GetResources	Retrieves information about resources in your answer systems.
GetStats	Returns information about the numbers of questions and question equivalence classes in each state in your answer bank systems.
ManageResources	Manages the resources in your answer bank and conversation systems.
TestRule	Tests a set of answer bank questions against a specified question equivalence rule.

GetJobStatus

Returns the status of a ManageResources update action. You can use this action to check whether a job is complete, for example to make sure that a new answer is available.

You must specify the list of job tokens to return the status for, and the name of the system, by setting JobTokens and SystemName.

Example

action=GetJobStatus&SystemName=MyAnswerBank&JobTokens=41,42,43

This action returns the status of the jobs with job IDs 41, 42, and 43.

Required Parameters

The following action parameters are required.

Parameter	Description
JobTokens	The list of job tokens for which to return the status.
SystemName	The name of the system to return status information for.

Optional Parameters

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

Response

You can retrieve the full response XSD by sending the GetResources action with Type set to XSD.

GetResources

The GetResources action allows you to retrieve information from your answer systems. You can use this action to retrieve the IDs for your resources to use in ManageResources actions.

You must specify the Type to determine the type of resources that the action returns.

The SystemName parameter allows you to return resources for a particular system. For some values of Type, you must set SystemName. For other types, if you do not specify SystemName, Answer Server returns resources that apply to all systems. Most resources are system-specific, but you can use this option to return XSD information for the general actions, when you set Type to XSD.

Example

http://12.3.4.56:12000/action=GetResources&SystemName=MyAnswerBank&Type=Question

This action retrieves question resources from the MyAnswerBank system. The response includes the question_id for the questions, which you can use in the ManageResources action, for example to add an answer.

Required Parameters

The following action parameters are required.

Parameter	Description
Type	The type of resource that you want to return.

Depending on the value of Type, the following parameter might also be required.

Parameter	Description
SystemName	The name of the system that you want to retrieve information for.

Optional Parameters

This action accepts the following optional parameters.

Parameter	Description
ExcludedIDs	The IDs of resources that you want to exclude from the results.
Filter	A filter to use to restrict the resources that return.
FirstResult	The number of the first result to return.
IDs	The IDs of resources that you want to return.
MaxResults	The maximum number of resources to return.
Sort	The methods to use to sort the results.
SystemName	The name of the system that you want to retrieve information for.

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

Response

You can retrieve the full response XSD by sending the GetResources action with Type set to XSD.

GetStats

Returns information about the numbers of questions and question equivalence classes in the system in each state. You must specify the system by setting SystemName.

The possible question state values are: incoming, answerable, needs_answer, answered, or rejected. Answer Server automatically assigns the incoming state to new questions, and updates the state to answered when you add the question to a question equivalence class. You can also manually define the question states by using the ManageResources action. For more information, refer to the Answer Server Administration Guide.

Answer Server assigns the question equivalence class a state according to whether it has a question equivalence rule. Question equivalence classes without a rule have the state incoming. Classes with a rule have the state published.

Example

action=GetStats&SystemName=MyAnswerBank

This action returns information about the questions in the MyAnswerBank system.

Required Parameters

The following action parameters are required.

Parameter	Description
SystemName	The name of the system that you want to retrieve statistics from.

Optional Parameters

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

Response

You can retrieve the full response XSD by sending the GetResources action with Type set to XSD.

NOTE: If there are no questions or question equivalence classes in a particular state, the action returns a stat tag for the status, with count zero.

ManageResources

For an answer bank system, you can use this action to add, modify, and delete questions and question equivalence classes. You can also use it to add and update the state of a question.

For a conversation system, you can use this action to add and delete conversation sessions.

You can also use this action to add and delete question contexts. The context specifies additional information to limit the scope of the question. In Fact Bank the context is a specific entity used in disambiguation, for example, you might set a context to specify that a user is asking questions about Cambridge UK, rather than Cambridge Massachusetts or Ontario. For Answer Bank or Passage Extractor, the context is a string that could, for example, come from a previous question. ManageResources returns a context ID that you can use in subsequent Ask actions.

NOTE: Conversation sessions and question contexts use licensed conversation slots. ManageResources returns an error if you do not have enough capacity. In this case, you must wait until a conversation session or question context expires, or delete one before you can create another.

This action requires a JSON object that specifies the update to request, and most updates also require a system name. You can use the GetResources action to retrieve the JSON schemas that you need to use to make each kind of update.

You update the system by sending a POST request with the JSON update.

For more information, refer to the Answer Server Administration Guide.

NOTE: You must use a POST request method.

Examples

action=ManageResources&SystemName=MyAnswerBank
Data={
   "operation": "add",
   "type":"question",
   "questions":[
      {"text":"Where do I sign up for the monthly newsletter?"}
   ]
}

This action adds the question Where do I sign up for the monthly newsletter? to the MyAnswerBank system.

action=ManageResources&SystemName=MyConversation
Data={
   "operation": "add",
   "type":"conversation_session"
}

This action adds a conversation session to the MyConversation system.

action=ManageResources  
Data={
   "type": "context",
   "operation": "add",
   "context": [{
      "system_name": "factbank1",
      "data": [{
         "code_type": "entity",
         "name": "Cambridge",
         "codes": ["Q350"]
      }]
   }]
}

This action creates a Fact Bank context to use with Ask actions.

To update a context it is possible to use a context token which is returned when a valid context ID is provided with an Ask action:

action=ManageResources  
Data={
	"type": "context",
	"operation": "update",
	"id": "13344074142776077059",
	"context": [ "14091358227749039740" ]
}

Required Parameters

The following action parameters are required.

Parameter	Description
Data	A JSON object that describes the update that you want to make.

Depending on the type of update that you want to make, the following action parameter might also be required.

Parameter	Description
SystemName	The name of the system that you want to update.

Optional Parameters

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

Response

You can retrieve the full response XSD by sending the GetResources action with Type set to XSD.

TestRule

Tests a set of questions that you specify against a question equivalence rule that you specify. You can use this action to test questions that are not in your Answer Bank Agentstore against new possible rules, before you index any content.

You specify the set of questions in the Questions parameter, which accepts a JSON object that contains the list of questions. You specify the rule in the Rule parameter.

The action returns details of the questions in the action that match the rule, and the ones that do not.

Example

action=TestRule&SystemName=MyAnswerBank&Questions={"text":["Why is the sky blue?","How do I return a defective item?"]}&Rule=sky AND blue

This action tests whether the two questions Why is the sky blue? and How do I return a defective item? match the rule sky AND blue.

Required Parameters

The following action parameters are required.

Parameter	Description
Questions	A JSON object that contains the questions that you want to test against the rule.
Rule	The question equivalence rule that you want to test the questions against.
SystemName	The name of the system that you want to update.

Optional Parameters

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

Response

You can retrieve the full response XSD by sending the GetResources action with Type set to XSD.

NLG Actions


NLG	Converts a JSON object containing the main parts of speech, and generates a natural language sentence.

NLG

The NLG action generates a natural language sentence from a JSON specification that includes details of the parts of speech to use. You can use this action, for example, to generate user-friendly responses for a user interface in a programmatic way.

NOTE: You must use a POST request method.

You send the JSON specification in the Spec parameter. You can retrieve the schema for this JSON object by sending a GetResources action with Type set to Schema.

NOTE: You can use NLG only if your license permits it. To enable the NLG action, you must also include the [NLG] section in your configuration file, with Enabled set to True, and JarPath set to the location of your SimpleNLG-4.4.8.jar file.

Example

action=NLG&Spec={
  "sentences": [
    {
      "subject": {
        "noun_phrases": [
          { "value": "the dog" }, 
          { "value": "your giraffe" }
        ]
      },
      "verb": {
        "verb_phrase": {
          "value": "chase",
          "modifiers": [ "quickly" ]
        }
      },
      "object": {
        "noun_phrases": [
          { "value": "the monkey" },
          { "value": "George" },
          { "value": "Martha" }
        ],
        "conjunction": "or"
      }
    }
  ]
}

This action generates the following sentence:

The dog and your giraffe quickly chase the monkey, George or Martha.

Required Parameters

The following action parameters are required.

Parameter	Description
Spec	A JSON object that defines the parts of speech that you want to use to generate natural language.

Optional Parameters

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

Response

You can retrieve the full response XSD by sending the GetResources action with Type set to XSD.

Status Actions


GetPid	Displays process ID.
GetStatus	Displays the ACI server's current status.

GetPid

Returns the ID of the process for Answer Server.

Example

http://12.3.4.56:9000/action=GetPid

This action requests the current process ID from Answer Server.

Optional Parameters

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

GetStatus

Returns the following details about the Answer Server setup (provided they have been configured):

version number
used ports

Example

http://12.3.4.56:12000/action=GetStatus

This action requests details about Answer Server.

Optional Parameters

This action accepts the following optional parameters.

Parameter	Description
SystemInfo	Whether to return additional information about the configured answer systems.

This action accepts the following standard ACI action parameters.

Parameter	Description
ActionID	A string to use to identify an ACI action.
FileName	The file to write output to.
ForceTemplateRefresh	Forces the server to load the template from disk.
Output	Writes output to a file.
ResponseFormat	The format of the action output.
Template	The template to use for the action output.
TemplateParamCSVs	A list of variables to use for the specified template.

Shared Action Parameters

This section describes parameters that are shared between multiple actions.

Parameters for All Actions

Parameters for All Actions

This section describes action parameters that you can use in all ACI actions.

Configuration Parameters

This section describes the configuration parameters that you can use to configure Answer Server.

AnswerSystemGroups Configuration Parameters

This section describes the configuration parameters that describe your custom groups of Answer Server systems.

N

The name of the configuration section that contains details of an Answer Server group. List one parameter for each group. The parameter name N must order consecutively from zero.

You can use system groups to allow you to send the Ask action to a custom group of your systems with a single system name (by specifying the group name in the SystemNames parameter for the Ask action). For example, you might create a group based on language or system type.

System groups might be useful if you have a custom user interface to ask questions, and your systems might change regularly. In this case you can use a static set of groups and change the Answer Server configuration to update the systems, rather than changing the user interface.

For each group that you specify in the [AnswerSystemGroups] section, you must create a [MyGroup] configuration section, in which you list the systems that the group contains. See MyGroup Configuration Parameters.

When you include one or more groups in SystemNames, Answer Server requests answers from your groups in the order that you specify them in SystemNames, and then requests answers from each system in the group in the order that you configure them in the group configuration. When a particular system exists in more than one group, Answer Server queries it only once.


Type:	String
Default:
Required:	No
Configuration Section:	AnswerSystemGroups
Example:	`0=AllEnglish 1=AllFrench 2=AllFactBank`
See Also:	MyGroup Configuration Parameters SystemNames

MyGroup Configuration Parameters

This section describes the configuration parameters that describe Answer Server system groups.

N

The name of an answer system that this group contains (that is, the name of the configuration section where you configure the system). List on parameter for each system. The parameter name N must order consecutively from zero.

In each [MyGroup] section, you specify the systems that you want Answer Server to request answers from when you use this group in the Ask action.

The order in which you specify the systems in the [MyGroup] section of the configuration file corresponds to the order in which Answer Server attempts to retrieve answers when you request answers from the group. When a particular system exists in more than one group, Answer Server queries it only once.


Type:	String
Default:
Required:	No
Configuration Section:	MyGroup
Example:	`0=AnswerBankEnglish 1=FactBankEnglish 2=PassageExtractorEnglish`
See Also:

Ask Configuration Parameters

This section describes the configuration parameters that set default values for parameters in the Ask action.

MaxResults

The default maximum number of answers to return in the Ask action, when the MaxResults action parameter is not set.

Answer Server returns the first N answers that it retrieves, where N is the value of MaxResults. It decides the top N results according to the Sort method.

You can set MaxResults to -1 if you do want to limit the number of results.


Type:	Integer
Default:	10
Required:	No
Configuration Section:	Ask
Example:	`MaxResults=5`
See Also:	Ask action MaxResults action parameter

Sort

The default method to use to sort the answers that Answer Server retrieves in the Ask action, when the Sort action parameter is not set. You can use one of the following options:

System (default). Sort the results by system. Answer Server uses the order that you specify the systems in the SystemNames parameter. If SystemNames is not set, Answer Server uses the order that you define the systems in the configuration file. If Answer Server retrieves enough answers from the first system to get to the specified MaxResults, it does not continue querying the other systems.
Confidence. Sort the results in order of the confidence score. Answers that have a higher confidence match for the request question return with a higher confidence score. In this case, Answer Server must query every system to get the MaxResults number of results with the highest score.

NOTE: Each answer system in Answer Server scores its answers independently, so scores from one system might not be comparable to scores from another.


Type:	String
Default:	System
Required:	No
Configuration Section:	Ask
Example:	`Sort=confidence`
See Also:	Ask action Sort action parameter

Timeout

The maximum number of seconds that Answer Server processes the Ask action for.

After the specified timeout, the Ask action returns any results that it has already received, but does not retrieve any further results.


Type:	Integer
Default:	0 (no timeout)
Required:	No
Configuration Section:	Ask
Example:	`Timeout=30`
See Also:	Ask action Timeout action parameter

AskContext Configuration Parameters

This section describes the configuration parameters that define the behavior of question contexts for the Ask action.

A question context is an entity that limits the scope of a question. For example, you might define a context to specify that a user is asking questions about Cambridge, UK, rather than Cambridge, Massachusetts or Ontario.

ExpirationIdleTime

The number of seconds that a question context can be idle for before it expires.

Answer Server runs an expiration operation regularly every ExpirationInterval. When a context has been idle (unused) for longer than the specified idle time when the expiration operation runs, the context expires.

If you send an Ask with an expired context, it returns an error.


Type:	Integer
Default:	300
Allowed Range:	Minimum: 10
Required:	No
Configuration Section:	AskContext
Example:	`ExpirationIdleTime=600`
See Also:

ExpirationInterval

The number of seconds between each scan of current question contexts to find any that have expired. You specify the length of time that a session must be idle before it expires by setting ExpirationIdleTime.

Set ExpirationInterval to zero (0) if you do not want to expire question contexts.


Type:	Integer
Default:	60
Required:	No
Configuration Section:	AskContext
Example:	`ExpirationInterval=60`
See Also:

Authorization Roles Configuration Parameters

The [AuthorizationRoles] section contains definitions for roles that enable particular sets of actions for particular clients, SSL identities, and GSS principals.

You must create a subsection for each authorization role that you define in the [AuthorizationRoles] configuration section.

If a connection matches one of the allowed clients, principals, or SSL identities, they have permission to perform the operations allowed by the role.

For example:

[AuthorizationRoles]
0=AdminRole
1=StandardUserRole
2=StatusOnlyRole

[AdminRole]
StandardRoles=Admin,ServiceControl
Clients=localhost
SSLIdentities=admin.example.com
GSSPrincipals=CONTENT01/[email protected]

[StandardUserRole]
StandardRoles=Query,ServiceStatus
SSLIdentities=admin.example.com,userserver.example.com
GSSPrincipals=CONTENT01/[email protected],CONTENT02/[email protected]

[StatusOnlyRole]
ServiceActions=GetStatus
SSLIdentities=general.example.com

You can use the ShowPermissions action to check the permissions for a user.

IMPORTANT: Make sure that you delete any deprecated RoleClients parameters from your configuration (where Role corresponds to a standard role name) to ensure Answer Server allows only your authorization role permissions.

N

The names of the authorization role configuration sections.

For the name of this configuration parameter, replace N with the zero-based rank number of the specified authorization role. For the parameter value, type the name of the authorization role configuration section.

You must number the authorization role parameters in consecutive order starting from 0 (zero).


Type:	String
Default:
Required:	No
Configuration Section:	AuthorizationRoles
Example:	`0=AdminRole 1=UserRole`
See Also:

My Authorization Role Configuration Parameters

The individual authorization role sections contain settings that define the authorization role.

You must create a subsection for each authorization role that you define in the [AuthorizationRoles] configuration section.

If a connection matches one of the allowed clients, principals, or SSL identities, they have permission to perform the operations allowed by the role.

For example:

[AuthorizationRoles]
0=AdminRole
1=StandardUserRole
2=StatusOnlyRole

[AdminRole]
StandardRoles=Admin,ServiceControl
Clients=localhost
SSLIdentities=admin.example.com
GSSPrincipals=CONTENT01/[email protected]

[StandardUserRole]
StandardRoles=Query,ServiceStatus
SSLIdentities=admin.example.com,userserver.example.com
GSSPrincipals=CONTENT01/[email protected],CONTENT02/[email protected]

[StatusOnlyRole]
ServiceActions=GetStatus
SSLIdentities=general.example.com

You can use the ShowPermissions action to check the permissions for a user.

Actions

A comma-separated list of ACI actions that you want to enable for this role configuration.

If a user connection matches one of the allowed clients, principals, or SSL identities, they have permission to perform the specified actions, regardless of whether they also have the appropriate standard role for that action.

You define the users that belong to a particular role by using Clients, GSSPrincipals, and SSLIdentities.

IMPORTANT: If you do not provide any authorization roles for a standard role, Answer Server uses the default client authorization for the role (see StandardRoles). If you define authorization only by actions, OpenText recommends that you configure an authorization role that disallows all users for all roles by default. For example:

[ForbidAllRoles]  
StandardRoles=*  
Clients=""

This configuration ensures that Answer Server uses only your action-based authorizations.


Type:	String
Default:
Required:	No
Configuration Section:	MyAuthorizationRole
Example:	`Actions=GetPID,GetVersion,GetStatus,GRL,GetLicenseInfo`
See Also:	Clients GSSPrincipals SSLIdentities

Clients

A comma-separated list of IP addresses (or host names) of clients that have authorization for the functions included in this role. There must be no space before or after a comma.

You can use wildcards in an IP address, but not in a host name. For example, 187.*.*.* includes any machine with an IP address that starts with 187, but *.microfocus.com is not permitted. You can also filter Clients by using CIDR notation.

You define the permissions that a particular role has by using StandardRoles, or by specifying the Actions and ServiceActions that you want the role to be able to use. You define the users that belong to a particular role by using Clients, GSSPrincipals, and SSLIdentities. If a connection matches one of the allowed clients, principals, or SSL identities, they have permission to perform the operations allowed by the role.


Type:	String
Default:
Required:	No
Configuration Section:	MyAuthorizationRole
Example:	`Clients=localhost,12.0.0.1`
See Also:	GSSPrincipals SSLIdentities

GSSPrincipals

A comma-separated list of Kerberos GSS principals that have authorization for the functions included in this role. You can include Wildcard values in the GSS principal names.

The Kerberos principal name consists of:

The Kerberos primary. This value might be the user name or service name (for example, KNOWLEDGEDISCOVERY/).
The instance name. The instance is the fully qualified host name; for example, myserver.example.com. This value is optional, and users do not usually have an instance.
The Kerberos realm. This value is normally the domain name in uppercase; for example, @EXAMPLE.COM.

To use GSS principals for permissions, you must set up Kerberos/GSS in your system (for example, you must set RequireGSSAuth).

You define the permissions that a particular role has by using StandardRoles, or by specifying the Actions and ServiceActions that you want the role to be able to use. You define the users that belong to a particular role by using Clients, GSSPrincipals, and SSLIdentities. If a connection matches one of the allowed clients, principals, or SSL identities, they have permission to perform the operations allowed by the role.


Type:	String
Default:
Required:	No
Configuration Section:	MyAuthorizationRole
Example:	`GSSPrincipals=KNOWLEDGEDISCOVERY01/[email protected],KNOWLEDGEDISCOVERY02/[email protected]`
See Also:	Clients SSLIdentities

ServiceActions

A comma-separated list of service actions that you want to enable for this role configuration.

You define the users that belong to a particular role by using Clients, GSSPrincipals, and SSLIdentities.

[ForbidAllRoles]  
StandardRoles=*  
Clients=""

This configuration ensures that Answer Server uses only your action-based authorizations.


Type:	String
Default:
Required:	No
Configuration Section:	MyAuthorizationRole
Example:	`ServiceActions=GetStatus`
See Also:	Clients GSSPrincipals SSLIdentities

SSLIdentities

A comma-separated list of SSL identities that have authorization for the functions included in this role.

You can include a tag prefix to specify whether the SSL identity is a DNS name (dns) or email address (email). If you do not specify a prefix, the server treats the identity as a DNS name. You can include Wildcard values in the SSL identities.

The SSL identity matches the subjectAltName DNS name or email in the certificate. If the subjectAltName does not exist, it falls back on the subject Common Name.

To use SSL identities for permissions, you must configure SSL in your Knowledge Discovery components, and your SSL setup must request certificates from connecting peers, by using SSLCACertificate and SSLCheckCertificate in your [SSLOptionN] configuration section.

You define the permissions that a particular role has by using StandardRoles, or by specifying the Actions and ServiceActions that you want the role to be able to use. You define the users that belong to a particular role by using Clients, GSSPrincipals, and SSLIdentities. If a connection matches one of the allowed clients, principals, or SSL identities, they have permission to perform the operations allowed by the role.


Type:	String
Default:
Required:	No
Configuration Section:	MyAuthorizationRole
Example:	`SSLIdentities=email:[email protected],dns:admin.example.com,webapp.example.com` This example authorizes a certificate with the `subjectAltName` values `email:[email protected]`, `dns:admin.example.com`, or `dns:webapp.example.com`.
See Also:	Clients GSSPrincipals

StandardRoles

A comma-separated list of standard roles that you want to enable for this role configuration.

You can use the following standard roles:

Admin. This role can perform administrative ACI actions.
Query. This role can perform non-administrative ACI actions.
ServiceControl. This role can perform administrative service actions.
ServiceStatus. This role can perform status service actions.

You can also use an asterisk (*) to represent all standard roles.

NOTE: The named standard roles do not overlap. If you want a particular authorization role to be able to perform all actions, you must include all the standard roles (for example, by setting StandardRoles to *), or ensure that you assign the clients, SSL identities, and so on, to all relevant roles.

You can also define more specific roles by using the Actions and ServiceActions parameters.

You define the users that belong to a particular role by using Clients, GSSPrincipals, and SSLIdentities. If a connection matches one of the allowed clients, principals, or SSL identities, they have permission to perform the operations allowed by the role.

By default, Answer Server allows the localhost client for the Admin and ServiceControl standard roles, and allows all clients for the Query and ServiceStatus roles. Setting any value for Clients, GSSPrincipals, or SSLIdentities overrides these default values.

IMPORTANT: Make sure that you delete any deprecated RoleClients parameters from your configuration (where Role corresponds to a standard role name). If you have clients allowed in the RoleClients parameters, Answer Server adds these permissions to any that you specify in authorization roles.


Type:	String
Default:
Required:	No
Configuration Section:	MyAuthorizationRole
Example:	`StandardRoles=Admin,ServiceControl`
See Also:	Clients GSSPrincipals SSLIdentities Actions ServiceActions

License Configuration Parameters

This section describes the license configuration parameters that specify licensing details.

GSSServiceName

The GSSAPI service name of the License Server. Specify only the service name part. You do not need to specify the fully qualified domain name.

If you have enabled GSSAPI authentication for License Server, Answer Server uses this value as the GSSAPI service name of the License Server.

IMPORTANT: If you set GSSServiceName, you must set LicenseServerHost to a fully qualified domain name (that is, for GSS authentication you cannot use localhost, an IP address, or a host without the domain name, even if these values resolve to the correct server).


Type:	String
Default:
Required:	No
Configuration Section:	Server
Example:	`GSSServiceName=LICENSESERVER`
See Also:

LicenseServerACIPort

The ACI port of License Server. This must be the Port specified in the License Server configuration file's [Server] section. This port is used to request licensing from License Server.


Type:	Long
Default:	None
Required:	Yes
Allowed range:	Minimum: 0 Maximum: 65536
Recommended range:	Minimum: 1025 Maximum: 65536
Configuration Section:	License
Example:	`LicenseServerACIPort=20000`
See Also:	LicenseServerHost LicenseServerTimeout LicenseServerRetries

LicenseServerHost

The IP address or host name of the machine that hosts the License Server.


Type:	String
Default:	None
Required:	Yes
Configuration Section:	License
Example:	`LicenseServerHost=1.23.45.6`
See Also:	LicenseServerACIPort LicenseServerTimeout LicenseServerRetries

LicenseServerRetries

The number of retries when connecting to the License Server.


Type:	Integer
Default:	5
Required:	No
Configuration Section:	License
Example:	`LicenseServerRetries=1`
See Also:	LicenseServerACIPort LicenseServerHost LicenseServerTimeout

LicenseServerTimeout

The time (in milliseconds) to timeout when connecting to License Server. Type the number of milliseconds after which requests that have been sent to the License Server time out if it does not respond.


Type:	Long
Default:	120000
Required:	No
Configuration Section:	License
Example:	`LicenseServerTimeout=600000`
See Also:	LicenseServerACIPort LicenseServerHost LicenseServerRetries

SSLConfig

The name of a section in the configuration file that specifies the settings for communicating with the License Server over SSL.

NOTE: Use this parameter only if you have configured your License Server to accept connections over SSL (by setting the SSLConfig parameter in the [Server] section of the License Server configuration file).


Type:	String
Default:
Required:	No
Configuration Section:	License
Example:	`SSLConfig=SSLOptions [SSLOptions] SSLCACertificate=trusted.crt SSLMethod=negotiate`
See Also:	LicenseServerACIPort LicenseServerHost

Logging Configuration Parameters

This section describes the configuration parameters used to create separate log files for different log message types (such as query, index, and application) and to determine how each stream is logged.

LogArchiveDirectory

Path to log archive directory. Type the directory in which you want the application to archive old log files when LogOldAction is set to Move.


Type:	String
Default:	./archive
Required:	No
Configuration Section:	Logging or LogStream or TaskName If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogArchiveDirectory=./archive`
See Also:	LogOldAction

LogCompressionMode

Specifies how old log files are compressed when the LogExpireAction parameter is set to Compress. You can set this to either zip or gz.


Type:	String
Default:	zip
Required:	No
Configuration Section:	Logging or LogStream If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogCompressionMode=gz`
See Also:	LogExpireAction

LogDirectory

Path to log directory. Type the directory in which you want the application to store the log files it creates.


Type:	String
Default:	./logs
Required:	No
Configuration Section:	Logging
Example:	`LogDirectory=./logs`
See Also:	LogArchiveDirectory LogFile

LogEcho

Displays logging messages on the console. Enable this parameter to display logging messages on the console.

NOTE: This setting has no effect if you are running the application as a Windows service.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	Logging or LogStream If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogEcho=True`
See Also:	LogArchiveDirectory

LogExpireAction

Determines how log files are handled when they exceed the maximum size. Type one of the following to determine how log files are handled when they exceed the LogMaxSizeKBs size:

Option	Description
`Compress`	The log file's name is appended with a timestamp, compressed and saved in the log directory. By default, this is a ZIP file. Use the `LogCompressionMode` parameter to specify another compression format.
`Consecutive`	The log file's name is appended with a number and saved in the log directory. When the next log file reaches its `LogMaxSizeKBs` size, it is appended with the next consecutive number.
`Datestamp`	The log file's name is appended with a timestamp and saved in the log directory.
`Previous`	The log file's name is appended with `.previous` and saved in the log directory. Every time a log file reaches its `LogMaxSizeKBs` size, it is given the same postfix so that it overwrites the old log file.
`Day`	Only one log file is created for each day and is appended with the current timestamp. Log files are archived after they reach the `LogMaxSizeKBs` size. NOTE: The `LogMaxSizeKBs` parameter takes precedence over the `LogExpireAction` parameter. Therefore, if you set `LogExpireAction` to `Day`, and the value for `LogMaxSizeKBs` results in more than one log file, multiple log files are generated for each day.


Type:	String
Default:	Datestamp
Required:	No
Configuration Section:	Logging or LogStream or TaskName If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogExpireAction=Compress`
See Also:	LogCompressionMode LogFile LogMaxSizeKBs

LogFile

Name of the log file that the application creates in the specified LogDirectory.


Type:	String
Default:	None
Required:	Yes
Configuration Section:	Logging or LogStream If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogFile=query.log`
See Also:	LogDirectory

LogHistorySize

The number of log messages to store in memory.


Type:	String
Default:	100
Required:	Yes
Allowed Range:	Minimum: 1 Maximum: 520
Configuration Section:	LogStream
Example:	`LogHistorySize=50`
See Also:	LogExpireAction

LogLevel

The type of messages that are logged. Type one of the following to determine the type of messages that are logged:

Option	Description
`Always`	Basic processes are logged. NOTE: This produces only minimal logging and no errors are logged.
`Error`	Errors are logged.
`Warning`	Errors and warnings are logged.
`Normal`	Errors, warnings, and basic processes are logged.
`Full`	Every occurrence is logged. NOTE: This produces a large log file and can affect performance.

The log levels are hierarchical from least logging to most logging. You can use the LogLevelMatch parameter to specify which messages are reported relative to the specified LogLevel. For example, if LogLevelMatch=LessThan and LogLevel=Warning, "Normal" and "Full" message types are reported.

Use the LogOutputLogLevel parameter to report the log level in the log.


Type:	String
Default:	Normal
Required:	No
Configuration Section:	Logging or LogStream If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogLevel=Warning`
See Also:	LogFile LogLevelMatch

LogLevelMatch

The messages reported relative to the specified LogLevel. The options are:

Option	Description
`Equal`	Only the message type specified by `LogLevel` is reported. For example, if `LogLevel=warning`, only warning messages are reported.
`LessThan`	The message types below the `LogLevel` setting are reported. For example, if `LogLevel=warning`, "Normal" and "Full" message types are reported.
`LessThanOrEqual`	The message type specified by `LogLevel` and any message type below that are reported. For example, if `LogLevel=warning`, "Normal", "Full", and "Warning" message types are reported.
`GreaterThan`	The message types above the `LogLevel` setting are reported. For example, if `LogLevel=warning`, "Error" and "Always" message types are reported.
`GreaterThanOrEqual`	The message type specified by `LogLevel` and any message type above that are reported. For example, if `LogLevel=warning`, "Error", "Always", and "Warning" message types are reported.


Type:	String
Default:	GreaterThanOrEqual
Required:	No
Configuration Section:	Logging or LogStream If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogLevelMatch=GreaterThanOrEqual`
See Also:	LogFile LogLevel LogOutputLogLevel

LogMaxLineLength

The number of characters a log entry can include before it is truncated. Increase this value when you want long actions to be logged in full.


Type:	Long
Default:	16384
Required:	No
Allowed Range:	Minimum: 0 Maximum: 2000000000
Recommended Range:	Minimum: 100 Maximum: 1000000
Configuration Section:	Logging or LogStream If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogMaxLineLength=24000`
See Also:	LogFile

LogMaxOldFiles

Maximum number of log files in the log directory. The maximum number of log files the specified LogDirectory can store before the application runs the specified LogOldAction. If you do not want to restrict how many log files the LogDirectory can store, type -1.


Type:	Long
Default:	-1 (unlimited)
Required:	No
Configuration Section:	Logging or LogStream or TaskName If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogMaxOldFiles=1000`
See Also:	LogDirectory LogOldAction

LogMaxSizeKBs

Maximum log file size (in kilobytes). If you do not want to restrict the log file size, type -1.

The LogExpireAction parameter determines how a log file is handled after it has reached its maximum size.

The LogMaxSizeKBs parameter is used for standard logging streams.


Type:	Long
Default:	1024
Required:	No
Configuration Section:	Logging or LogStream or TaskName If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogMaxSizeKBs=1000`
See Also:	LogExpireAction

LogOldAction

Determines how log files are handled when the maximum number of log files is exceeded. Type one of the following to determine how log files are handled when the LogDirectory has reached the maximum number of log files, as determined by the LogMaxOldFiles parameter:

Option	Description
`Delete`	The log files are deleted.
`Move`	The log files are moved to the specified `LogArchiveDirectory`.


Type:	String
Default:	Delete
Required:	No
Configuration Section:	Logging or LogStream If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogOldAction=Move`
See Also:	LogArchiveDirectory LogDirectory LogMaxOldFiles

LogOutputLogLevel

Determines whether the log level is reported in the log. By default, the log entry includes the log level of a message.


Type:	Boolean
Default:	True
Required:	No
Configuration Section:	Logging or LogStream If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogLevel=Always LogOutputLogLevel=True` In this example, `Always` is added to the log message: `19/12/2012 11:50:21 [6] 00-Always: ACI Server attached to port 9992`
See Also:	LogLevel

LogOutputSeverity

Assigns each log message a severity rating from 0–99. 0 is the least serious, 99 is the most serious. By default, log messages include severity ratings.


Type:	Boolean
Default:	True
Required:	No
Configuration Section:	Logging or LogStream If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogOutputSeverity=True`
See Also:	LogLevel LogOutputLogLevel

LogSysLog

Writes messages to the Microsoft Windows or Linux system log. Enable this parameter to write messages to the Linux Syslog or the Windows Event Log.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	Logging or LogStream If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogSysLog=True`
See Also:

LogTime

Displays time with each log entry. Enable this parameter to display the current time next to each log entry in the log file.


Type:	Boolean
Default:	True
Required:	No
Configuration Section:	Logging or LogStream If you set this parameter in the `Logging` and `LogStream` sections, the setting in the `LogStream` section takes precedence for the specified log stream.
Example:	`LogTime=False`
See Also:	LogFile

LogTypeCSVs

List of message types to log. Type one or more of the following message types to specify the type of messages written to the associated log file. If you want to type multiple message types, separate them with commas (there must be no space before or after a comma):

Option	Description
All Components
---	---
`Action`	Logs actions and related messages.
`Application`	Logs application-related occurrences.
Answer Server
`AnswerBank`	Logs information about your answer bank systems.
`Conversation`	Logs information about your conversation systems.
`FactBank`	Logs information about your fact bank systems.
`PassageExtractor`	Logs information about your passage extractor systems.


Type:	String
Default:	None
Required:	Yes
Configuration Section:	LogStream
Example:	`LogTypeCSVs=Application,Index`
See Also:	LogFile

NLG Configuration Parameters

This section describes the configuration parameters that enable the NLG (Natural Language Generator) action and define the location of the required files.

Enabled

Set Enabled to True to enable the NLG action for natural language generation.

NOTE: You can use NLG only if your license includes it. If you enable NLG, and your license does not allow it, Answer Server does not start.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	NLG
Example:	`Enabled=True`
See Also:	NLG action

JarPath

The path to the SimpleNLG-4.4.8.jar file that Answer Server uses for natural language generation in the NLG action.

NOTE: If you enable NLG, and your JarPath does not resolve to a directory that contains the SimpleNLG-4.4.8.jar file, Answer Server does not start.


Type:	String
Default:
Required:	Yes, if you have set Enabled to `True`.
Configuration Section:	NLG
Example:	`JarPath=C:\KnowledgeDiscovery\AnswerServer\NLG\`
See Also:

Paths Configuration Parameters

This section describes the configuration parameters that you can use to specify the location of files used by the ACI server. These parameters are set in the [Paths] section of the configuration file.

AdminFile

The full path to the Knowledge Discovery Admin (admin.dat) file.


Type:	String
Default:	the `admin.dat` file in the working directory
Required:	No
Configuration Section:	Paths
Example:	`AdminFile=modules/admin.dat`
See Also:

GSSAPILibrary

The path to the GSSAPI shared library or DLL that the application uses. You can use an absolute path, or a path relative to the server executable file.

Depending on your system configuration, Answer Server attempts to detect the appropriate library to use. However, if you use Kerberos or GSSAPI security in your setup, OpenText recommends that you set an explicit value for this parameter.


Type:	String
Default:
Required:	No
Configuration Section:	Paths
Example:	`GSSAPILibrary=D:/knowledgediscovery/gss/gssapi.dll`
See Also:

TempDir

The path of a directory where the server can store temporary files. ACI servers use this directory to store files that were uploaded in multipart requests, but it can also be used for other temporary files.


Type:	String
Default:	`./temp`
Required:	No
Configuration Section:	Paths
Example:	`TempDir=temp`
See Also:

TemplateDirectory

The path to the directory that contains your XSL templates. You can use XSL templates to transform action responses.


Type:	String
Default:	`acitemplates`
Required:	No
Configuration Section:	Paths
Example:	You can use an absolute or relative path: `TemplateDirectory=D:/Server/templates TemplateDirectory=templates`
See Also:	XSLTemplates

Query Configuration Parameters

DEPRECATED: The [Query] configuration section is deprecated from Answer Server version 11.5.0. Use the [Ask] section name instead.

This configuration section name is still available for existing implementations, but it might be incompatible with new functionality. The section name might be deleted in future.

This section describes the configuration parameters that set default values for parameters in the Ask action.

MaxResults

The default maximum number of answers to return in the Ask action, when the MaxResults action parameter is not set.

Answer Server returns the first N answers that it retrieves, where N is the value of MaxResults. It decides the top N results according to the Sort method.

You can set MaxResults to -1 if you do want to limit the number of results.


Type:	Integer
Default:	10
Required:	No
Configuration Section:	Ask
Example:	`MaxResults=5`
See Also:	Ask action MaxResults action parameter

Sort

The default method to use to sort the answers that Answer Server retrieves in the Ask action, when the Sort action parameter is not set. You can use one of the following options:

System (default). Sort the results by system. Answer Server uses the order that you specify the systems in the SystemNames parameter. If SystemNames is not set, Answer Server uses the order that you define the systems in the configuration file. If Answer Server retrieves enough answers from the first system to get to the specified MaxResults, it does not continue querying the other systems.
Confidence. Sort the results in order of the confidence score. Answers that have a higher confidence match for the request question return with a higher confidence score. In this case, Answer Server must query every system to get the MaxResults number of results with the highest score.

NOTE: Each answer system in Answer Server scores its answers independently, so scores from one system might not be comparable to scores from another.


Type:	String
Default:	System
Required:	No
Configuration Section:	Ask
Example:	`Sort=confidence`
See Also:	Ask action Sort action parameter

Secure Socket Layer Parameters

This section describes the configuration parameters used to configure Secure Socket Layer (SSL) connections between components.

NOTE: These parameters usually appear in the [SSLOptions] section of the configuration file.

SSLCACertificate

The Certificate Authority (CA) certificate file of a trusted authority. The component trusts communication only with a peer that provides a certificate signed by the specified CAs.

You can specify the path to a file containing multiple CA certificates in PEM format. The file can contain certificates identified by sequences like the following example:

----BEGIN CERTIFICATE----  
... (CA certificate in base64 encoding) ...  
----END CERTIFICATE----

You can insert text before, between, and after the certificates to be used as descriptions of the certificates.

When you set SSLCACertificate, it implicitly sets SSLCheckCertificate to True. In this case, you can set SSLCheckCertificate to False to allow Answer Server the component to fill in any chain required for the SSLCertificate by using the certificates that you specify in SSLCACertificate, without requiring a certificate from the connected peer.


Type:	String
Default:	None
Required:	No
Configuration Section:	SSLOptionN
Example:	`SSLCACertificate=trusted.crt`
See Also:	SSLConfig

SSLCACertificatesPath

The path to a directory containing multiple CA certificates, in PEM format, to check against. Each file must contain one CA certificate. The files are looked up by the CA subject name hash value, which must be available. If more than one CA certificate with the same name hash value exists, the extension must be different (for example, 9dd6633f0.0, 9dd6633f0.1, and so on). The search is performed in the order of the extension number, regardless of other properties of the certificates.

CAUTION: If several CA certificates matching the name, key identifier, and serial number condition are available, only the first one is examined. This might lead to unexpected results if the same CA certificate is available with different expiration dates. If a certificate expired verification error occurs, no other certificate is searched. Make sure expired certificates are not mixed with valid ones.

For more information, refer to the documentation for OpenSSL.

When you set SSLCACertificatesPath, it implicitly sets SSLCheckCertificate to True. In this case, you can set SSLCheckCertificate to False to allow Answer Server to fill in any chain required for the SSLCertificate by using the certificates that you specify in SSLCACertificatesPath, without requiring a certificate from the connected peer.


Type:	String
Default:	None
Required:	No
Configuration Section:	SSLOptionN
Example:	`SSLCACertificatesPath=C:\CACERTS\`
See Also:	SSLCACertificate SSLConfig

SSLCertificate

The SSL Certificate file to use to identify this component to a peer. You can specify a single certificate in ASN1 or PEM format, or a chain certificate in PEM format. The chain certificate consists of the end-entity certificate, any intermediate certificates, ending with the root CA certificate.

This parameter requires a matching SSLPrivateKey value. If you use a chain certificate, the SSLPrivateKey refers only to the end-entity certificate.

You can specify the file name with an absolute or relative path to the location of the certificate file.


Type:	String
Default:	None
Required:	Yes
Configuration Section:	SSLOptionN
Example:	`SSLCertificate=host1.crt SSLPrivateKey=host1.key`
See Also:	SSLConfig SSLPrivateKey

SSLCheckCertificate

Set SSLCheckCertificate to True to require Answer Server to request a certificate signed by a trusted authority from connected peers.

When SSLCheckCertificate is set to False, communications are encrypted, but certificates are not requested from peers.

When you set SSLCACertificate, it implicitly sets SSLCheckCertificate to True. In this case, you can set SSLCheckCerticate to False to allow Answer Server to fill in any chain required for the SSLCertificate by using the certificates that you specify in SSLCACertificate and SSLCACertificatesPath, without requiring a certificate from the connected peer.


Type:	Boolean
Default:	True if SSLCACertificate and SSLCACertificatesPath are set. False if SSLCACertificate and SSLCACertificatesPath are not set.
Required:	No
Configuration Section:	SSLOptionN
Example:	`SSLCheckCertificate=True`
See Also:	SSLConfig SSLCACertificate

SSLCheckCommonName

Verifies the identity of the peer. Specifies whether the host name listed in the peer's certificate (that is, the CommonName or "CN" attribute) resolves to the same IP address as the peer itself, as determined by the network connection.

For example, if the host name in a certificate is certificates.example.com and resolves to an IP address of 12.3.4.56, the peer must share the same IP address.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	SSLOptionN
Example:	`SSLCheckCommonName=True`
See Also:	SSLConfig

SSLCipherSuite

The available ciphers to use to negotiate SSL connections. You can use this parameter to set an explicit list of ciphers to allow, or to disallow specific ciphers.

The parameter uses the OpenSSL cipher string format. For details of this format, see the documentation for OpenSSL (TLS 1.2 and earlier and TLS 1.3) or apache mod_ssl.

There is no default value for this parameter, which means that Answer Server uses the default cipher list.

If you set SSLCipherSuite, but do not specify any valid ciphers for your SSLMethod, Answer Server does not start. For example, Answer Server does not start if you set SSLMethod to TLS1.3, but SSLCipherSuite contains only ciphers for TLS 1.2 or earlier. However, if SSLCipherSuite includes both types of cipher, Answer Server ignores the ciphers that are not relevant to the SSLMethod.

NOTE: When SSLMethod is set to Negotiate, you can set SSLCipherSuite to use ciphers for only TLS 1.3 or for only TLS 1.2 or earlier. In this case, when Answer Server negotiates a SSL/TLS version that has configured ciphers, it uses only the allowed ciphers. However, when it negotiates a SSL/TLS version that has no configured ciphers, it uses the default cipher list.


Type:	String
Default:	None
Required:	No
Configuration Section:	SSLOptionN
Example:	`SSLCipherSuite=DEFAULT:!RC4`
See Also:	SSLConfig

SSLMethod

Specifies which SSL protocol is used. The options are:

TLSV1.3
TLSV1.2
TLSV1
SSLV3
Negotiate - negotiate, and use the highest protocol supported by both client and server. In earlier versions of Answer Server, this method is known as SSLV23.

OpenText recommends that you use TLSV1.3, unless interoperability with older systems requires use of less secure protocols.


Type:	String
Default:	None
Required:	Yes
Configuration Section:	SSLOptionN
Example:	`SSLMethod=TLSV1.3`
See Also:	SSLConfig

SSLPrivateKey

The private security key for the SSL certificate. It can be either ASN1 or PEM format. This parameter requires a matching SSLCertificate value.

You can specify the file name with an absolute or relative path to the location of the key file.


Type:	String
Default:	None
Required:	Yes
Configuration Section:	SSLOptionN
Example:	`SSLCertificate=host1.crt SSLPrivateKey=host1.key`
See Also:	SSLConfig SSLCertificate SSLPrivateKeyPassword

SSLPrivateKeyPassword

The password for the file defined in SSLPrivateKey. The password can be in plain text, or basic or AES encryption format.


Type:	String
Default:	None
Required:	No
Configuration Section:	SSLOptionN
Example:	`[SSLOption0] SSLCertificate=host1.crt SSLPrivateKey=host1.key SSLPrivateKeyPassword=PvKey1559` In this example, the private key password to the file `host1.key` is written in plain text. `... [SSLOption0] SSLCertificate=host1.crt SSLPrivateKey=host1.key SSLPrivateKeyPassword=9s7BxMjD2d3M3t7awt/J8A` In this example, the private key password to the file `host1.key` has basic encryption.
See Also:	SSLConfig SSLPrivateKey

Security Configuration Parameters

The [Security] configuration section lists the security types that you are using, and contains a subsection for each security type. In each subsection, you can specify the settings to apply to each security type.

For example:

[Security]
SecurityInfoKeys=Mykeyfile.ky
0=NT_V4
1=Netware_V4
2=Notes_V4
3=Exchange_V4
4=Documentum_V4
			
[NT_V4]
Type=AUTONOMY_SECURITY_V4_NT_MAPPED
			
[Netware_V4]
Type=AUTONOMY_SECURITY_V4_NETWARE_MAPPED
			
[Notes_V4]
Type=AUTONOMY_SECURITY_V4_NOTES_MAPPED
			
[Exchange_V4]
Type=AUTONOMY_SECURITY_V4_EXCHANGE_GRPS_MAPPED
			
[Documentum_V4]
Type=AUTONOMY_SECURITY_V4_DOCUMENTUM_MAPPED
EscapedEntries=False

N

The name of the security type.

For the configuration parameter name, replace N with the zero-based rank number for the security type. For the parameter value, specify the name of the security type configuration section.

NOTE: You must number the security type parameters in consecutive order starting from 0 (zero).


Type:	String
Default:
Required:	Yes
Configuration Section:	Security
Example:	`0=NT_V4 1=Netware_V4 2=Notes_V4 3=Exchange_V4 4=Documentum_V4`
See Also:

SecurityInfoKeys

The security keys that Answer Server uses to encrypt and decrypt the security information that it uses for user security.

To use AES encryption (recommended), set SecurityInfoKeys to the file name and path of the AES key file. Answer Server then uses this key file to encrypt and decrypt the SecurityInfo tokens. For information about how to create a key file, refer to the Knowledge Discovery Administration Guide.

For older systems that use TEA encryption, set SecurityInfoKeys to four signed 32-bit integers (between 0 and 2147483647), separated with commas. There must be no space before or after the commas.

NOTE: You must set SecurityInfoKeys to the same value that you use for all other components that use an AES key file or four-number security identifier.


Type:	String
Default:
Required:	Yes
Configuration Section:	Security
Example:	`SecurityInfoKeys=mykeyfile.ky`
See Also:

Security Type Configuration

You must create a [MySecurityType] configuration section for each security type listed in the [Security] section.

For example:

[NT_V4]
Type=AUTONOMY_SECURITY_V4_NT_MAPPED

[Netware_V4]
Type=AUTONOMY_SECURITY_V4_NETWARE_MAPPED
			
[Notes_V4]
Type=AUTONOMY_SECURITY_V4_NOTES_MAPPED
			
[Exchange_V4]
Type=AUTONOMY_SECURITY_V4_EXCHANGE_GRPS_MAPPED
			
[Documentum_V4]
Type=AUTONOMY_SECURITY_V4_DOCUMENTUM_MAPPED
EscapedEntries=False
			
[Generic_V4]
Type=AUTONOMY_SECURITY_V4_GENERIC_MAPPED
Logging=True
EscapedEntries=True
SecurityACLFormat=<E=B!>:U:<U=SLE+>:G:<G=SLE+>:NU:<NU=SLE->:NG:<NG=SLE->
SecurityACLCheck=NU=[DU]?F:-,NG=[DG]?F:-,E=1?P:-,U=[DU]?P:-,G=[DG]?P:F

EscapedEntries

Set EscapedEntries to True if you want the security plug-in to unencode any percent-encoded characters that occur in user and group names in a URL (that is, it converts the characters from the percent-encoded sequence to the original character).


Type:	Boolean
Default:	False
Required:	Yes, if user names or group names contain non-alphanumeric characters
Configuration Section:	`MySecurityType`
Example:	`EscapedEntries=True`
See Also:

Logging

Set Logging to True to record log messages for this security type. The type of logging messages varies for each available Type.

Answer Server writes the log messages to a file in your log file directory, named Mapped_Security_``MySecurityType, where MySecurityType is the name of the configuration section for the security type.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	`MySecurityType`
Example:	`Logging=True`
See Also:	Type

SecurityACLCheck

The methods to use to process the custom access control list (ACL). This parameter is used only by the AUTONOMY_SECURITY_V4_GENERIC_MAPPED security type.

To define a generic security type, you must set SecurityACLFormat and SecurityACLCheck. For more information, refer to the Document Security Administration Guide.

Specify the ACL Format

SecurityACLFormat=ACLFormatString

where,

Variable	Format
`ACLFormatString`	`String ACLFormatFields String`
`ACLFormatFields`	`ACLField
`ACLField`	`"<" ACLFieldName "=" Properties ">"`
`ACLFieldName`	`NonEmptyString`
`Properties`	`Property
`Property`	`"B"
`String`	`""
`NonEmptyString`	`Character String`

Specify the Security Checks

SecurityACLCheck=ACLCheckString

where,

Variable	Format
`ACLCheckString`	`CheckString
`CheckString`	`ACLValue Operator UserValue "?" MatchAction ":" NoMatchAction`
`ACLValue`	`"'" String "'"
`Operator`	`"="
`UserValue`	`String
`ValueType`	`"U"
`MatchAction`	`Action`
`NoMatchAction`	`Action`
`Action`	`"P"

Syntax

The following table defines the property types used in the SecurityACLFormat configuration parameter. Acceptable types appear in parentheses.

Property	Definition
`B`	Boolean type (equivalent to Digit type)
`D`	Digit type
`S`	String type
`L`	Comma-separated list (S)
`E`	Encrypted (S)
`X`	Escaped (S)
`C`	Case insensitive (S)
`+`	Positive terms (S)
`-`	Negative terms (S)
`!`	Everyone flag (B

The following table describes the operators that you can use between the ACLValue and UserValue in the SecurityACLCheck configuration parameter:

Operator	Definition	Usage
`=`	Returns true if there is at least one match.
`~=`	Returns true if there is at least one match, or if there is nothing in the `ACLValue` to check.
`&=`	Returns true only if every value in `ACLValue` matches a value in `UserValue`. There must be at least one match.	Valid only when the `UserValue` is `[G]`, `[GROUP]`, `[DG]`, or `[DOMAINGROUP]`.
`~&=`	Returns true if every value in `ACLValue` matches a value in `UserValue`, or if there is nothing in the `ACLValue` to check.	Valid only when the `UserValue` is `[G]`, `[GROUP]`, `[DG]`, or `[DOMAINGROUP]`.
`=~`	Returns true if there is at least one match, or if there is nothing in the `UserValue` to check.	Valid only when the `UserValue` is `[G]`, `[GROUP]`, `[DG]`, or `[DOMAINGROUP]`.
`=&`	Returns true only if every value in `UserValue` matches a value in `ACLValue`. There must be at least one match.	Valid only when the `UserValue` is `[G]`, `[GROUP]`, `[DG]`, or `[DOMAINGROUP]`.
`=&~`	Returns true if every value in `UserValue` matches a value in `ACLValue`, or if there is nothing in the `UserValue` to check.	Valid only when the `UserValue` is `[G]`, `[GROUP]`, `[DG]`, or `[DOMAINGROUP]`.

The following table describes the possible values of ValueType in the SecurityACLCheck configuration parameter:

Value Type	Definition
`[U], [USER]`	User name only
`[DU], [DOMAINUSER]`	Domain\User name or User name if \ exists
`[G], [GROUP]`	Group only
`[DG], [DOMAINGROUP]`	Domain\Group or Group if \ exists
`[D], [DOMAIN]`	Domain only
`[P], [PASSWORD]`	Password only

The following table describes the possible actions that can be used in the SecurityACLCheck configuration parameter:

Action	Definition
`F, FAIL`	Fail
`P, PASS`	Pass
`C, -, CONTINUE`	Continue
`Number N`	Skip the next N checks


Type:	String
Default:
Required:	Yes
Configuration Section:	`MySecurityType`
Example:	`SecurityACLFormat=<E=B!>:U:<U=SLE+>:G:<G=SLE+>:NU:<NU=SLE->:NG:<NG=SLE-> SecurityACLCheck=NU=[DU]?F:-,NG=[DG]?F:-,E=1?P:-,U=[DU]?P:-,G=[DG]?P:F`
See Also:	SecurityACLFormat

SecurityACLFormat

The format of your custom access control list (ACL). This parameter is used only by the AUTONOMY_SECURITY_V4_GENERIC_MAPPED security type.

To define a generic security type, you must set SecurityACLFormat and SecurityACLCheck. For more information, refer to the Document Security Administration Guide.

Specify the ACL Format

SecurityACLFormat=ACLFormatString

where,

Variable	Format
`ACLFormatString`	`String ACLFormatFields String`
`ACLFormatFields`	`ACLField
`ACLField`	`"<" ACLFieldName "=" Properties ">"`
`ACLFieldName`	`NonEmptyString`
`Properties`	`Property
`Property`	`"B"
`String`	`""
`NonEmptyString`	`Character String`

Specify the Security Checks

SecurityACLCheck=ACLCheckString

where,

Variable	Format
`ACLCheckString`	`CheckString
`CheckString`	`ACLValue Operator UserValue "?" MatchAction ":" NoMatchAction`
`ACLValue`	`"'" String "'"
`Operator`	`"="
`UserValue`	`String
`ValueType`	`"U"
`MatchAction`	`Action`
`NoMatchAction`	`Action`
`Action`	`"P"

Syntax

The following table defines the property types used in the SecurityACLFormat configuration parameter. Acceptable types appear in parentheses.

Property	Definition
`B`	Boolean type (equivalent to Digit type)
`D`	Digit type
`S`	String type
`L`	Comma-separated list (S)
`E`	Encrypted (S)
`X`	Escaped (S)
`C`	Case insensitive (S)
`+`	Positive terms (S)
`-`	Negative terms (S)
`!`	Everyone flag (B

The following table describes the operators that you can use between the ACLValue and UserValue in the SecurityACLCheck configuration parameter:

Operator	Definition	Usage
`=`	Returns true if there is at least one match.
`~=`	Returns true if there is at least one match, or if there is nothing in the `ACLValue` to check.
`&=`	Returns true only if every value in `ACLValue` matches a value in `UserValue`. There must be at least one match.	Valid only when the `UserValue` is `[G]`, `[GROUP]`, `[DG]`, or `[DOMAINGROUP]`.
`~&=`	Returns true if every value in `ACLValue` matches a value in `UserValue`, or if there is nothing in the `ACLValue` to check.	Valid only when the `UserValue` is `[G]`, `[GROUP]`, `[DG]`, or `[DOMAINGROUP]`.
`=~`	Returns true if there is at least one match, or if there is nothing in the `UserValue` to check.	Valid only when the `UserValue` is `[G]`, `[GROUP]`, `[DG]`, or `[DOMAINGROUP]`.
`=&`	Returns true only if every value in `UserValue` matches a value in `ACLValue`. There must be at least one match.	Valid only when the `UserValue` is `[G]`, `[GROUP]`, `[DG]`, or `[DOMAINGROUP]`.
`=&~`	Returns true if every value in `UserValue` matches a value in `ACLValue`, or if there is nothing in the `UserValue` to check.	Valid only when the `UserValue` is `[G]`, `[GROUP]`, `[DG]`, or `[DOMAINGROUP]`.

The following table describes the possible values of ValueType in the SecurityACLCheck configuration parameter:

Value Type	Definition
`[U], [USER]`	User name only
`[DU], [DOMAINUSER]`	Domain\User name or User name if \ exists
`[G], [GROUP]`	Group only
`[DG], [DOMAINGROUP]`	Domain\Group or Group if \ exists
`[D], [DOMAIN]`	Domain only
`[P], [PASSWORD]`	Password only

The following table describes the possible actions that can be used in the SecurityACLCheck configuration parameter:

Action	Definition
`F, FAIL`	Fail
`P, PASS`	Pass
`C, -, CONTINUE`	Continue
`Number N`	Skip the next N checks

For more information, refer to the Document Security Administration Guide.


Type:	String
Default:
Required:	Yes
Configuration Section:	`MySecurityType`
Example:	`SecurityACLFormat=<E=B!>:U:<U=SLE+>:G:<G=SLE+>:NU:<NU=SLE->:NG:<NG=SLE-> SecurityACLCheck=NU=[DU]?F:-,NG=[DG]?F:-,E=1?P:-,U=[DU]?P:-,G=[DG]?P:F`
See Also:	SecurityACLCheck

Type

The name of this security type. You can use one of the following values to indicate which security type is used for documents in the database:

AUTONOMY_SECURITY_V4_NOTES_MAPPED
AUTONOMY_SECURITY_V4_DOCUMENTUM_MAPPED
AUTONOMY_SECURITY_V4_PCDOCS_MAPPED
AUTONOMY_SECURITY_V4_NT_MAPPED
AUTONOMY_SECURITY_V4_GENERIC_MAPPED
AUTONOMY_SECURITY_V4_WORKSITE_MAPPED
AUTONOMY_SECURITY_NOTES
AUTONOMY_SECURITY_ODBC
AUTONOMY_SECURITY_ORACLE
AUTONOMY_SECURITY_NT
AUTONOMY_SECURITY_EXCHANGE
AUTONOMY_SECURITY_EXCHANGE_MAPPED
AUTONOMY_SECURITY_UNIX_MAPPED
AUTONOMY_SECURITY_NETWARE
AUTONOMY_SECURITY_NETWARE_MAPPED
AUTONOMY_SECURITY_OPENTEXT
AUTONOMY_SECURITY_OPENTEXT_MAPPED
AUTONOMY_SECURITY_DOCUMENTUM
AUTONOMY_SECURITY_SHAREPOINT_MAPPED
AUTONOMY_SECURITY_FILENET_MAPPED
AUTONOMY_SECURITY_NONE
AUTONOMY_SECURITY_UNSUPPORTED


Type:	String
Default:
Required:	Yes
Configuration Section:	`MySecurityType`
Example:	`Type=AUTONOMY_SECURITY_V4_NOTES_MAPPED`
See Also:

WorksiteSecurityModel

The submodel to use for Worksite security. This parameter applies only to the AUTONOMY_SECURITY_V4_WORKSITE_MAPPED security type.

By default, Answer Server uses a pessimistic security model, which means that it checks whether a user is denied before checking whether the user is allowed. Set WorksiteSecurityModel to OPTIMISTIC to use an optimistic security model instead, which checks whether the user is allowed first.


Type:	String
Default:	PESSIMISTIC
Required:	No
Configuration Section:	`MySecurityType`
Example:	`WorksiteSecurityModel=OPTIMISTIC`
See Also:

Server Configuration Parameters

This section describes server configuration parameters.

AllowedQueryParameters

A list of parameters that Answer Server must pass through in requests. You can use this parameter to allow you to include additional parameters that Answer Server forwards to its child servers (such as the Answer Bank Agentstore). For example, you might want to add additional restrictions to the query logic, get additional response information, or add custom tracking information to the queries.

Separate multiple parameters with commas. There must be no space before or after a comma.


Type:	String
Default:
Required:	No
Configuration Section:	Server
Example:	`AllowedQueryParameters=DatabaseMatch,MaxID`
See Also:

ExplicitHost

The IP address that the server should use on the host machine. If you install the server on a machine with more than one network interface, you can use this parameter to specify the IP address to use. If the machine only has one network interface, you do not need to set this parameter.


Type:	String
Default:
Required:	No
Configuration Section:	Server
Example:	`ExplicitHost=10.0.0.1`
See Also:

GSSServiceName

The GSSAPI service name that you want to use for the Answer Server service. You must specify the GSSAPI service name, instance name (fully qualified host name), and the Kerberos realm (normally the domain name in upper case).

You can also set GSSServiceName to an asterisk (*) to allow clients to authenticate to any service principal in the Answer Server service's keytab, rather than requiring you to select a single principal.

If you enable GSSAPI authentication, Answer Server uses this value as the GSSAPI service name to identify itself. You enable GSSAPI authentication by setting the RequireGSSAuth parameter in the appropriate section:

ACI port: [Server] RequireGSSAuth
Service port: [Service] RequireGSSAuth


Type:	String
Default:
Required:	No
Configuration Section:	Server
Example:	`GSSServiceName=MYSERVICE/[email protected]`
See Also:

JSONFormat

The JSON format to use for an ACI action response when the action has ResponseFormat set to json. You can use one of the following options:

json. The most recent JSON format. In version 25.3, this value is equivalent to json/1. In future versions, this value might be updated to use a new type of JSON format.
json/0. An older JSON format that returns single-element lists as objects, rather than arrays. This format was the default JSON format before Answer Server version 12.0.
json/1. A newer JSON format that returns single-element lists as arrays, for consistency with multiple-element lists.
simplejson. This format is similar to the json/1 format, but it does not use $ nodes to represent XML nodes unless the equivalent XML node contains attributes. This response format also does not use autn: prefixes in node names.


Type:	String
Default:	json
Required:	No
Configuration Section:	Server
Example:	`JSONFormat=simplejson`
See Also:

KeepAliveInterval

The number of seconds within which data must be received over a TCP socket. When this timeout value expires, the connection is closed.


Type:	Long
Default:	15
Required:	No
Configuration Section:	Server
Example:	`KeepAliveInterval=20`
See Also:

Language

The language to use for stemming. This parameter applies only to fact bank and passage extractor systems.

Stemming is the process of reducing related words, such as plurals and verb forms, to a common linguistic root. For example, in English, helping, helped, and helps all derive from the common root help.

Answer Server uses stemming for fact bank and passage extractor to improve question parsing and answer matching.

Stemming rules are language-dependent. To get the best possible results, you must specify the language that you use in your questions. Ideally, this language is the same as the language of your fact bank or passage extractor grammar file.

The Fact Bank grammar file is currently available in English, French, German, Italian, Portuguese, and Spanish. If you are interested in using fact bank or passage extractor in another language, contact your OpenText account manager.

Answer Server supports the same languages for stemming as the Content component. For more information, refer to Knowledge Discovery Expert.


Type:	String
Default:	English
Required:	No
Configuration Section:	Server or MySystem If you configure `Language` in both the `[Server]` and system configuration sections, the system configuration overrides the server configuration for that system.
Example:	`Language=French`
See Also:	LanguageDirectory StopList

LanguageDirectory

The directory that contains any language files (such as the stop list file).


Type:	String
Default:	Answer Server working directory
Required:	No
Configuration Section:	Server or MySystem If you configure `LanguageDirectory` in both the `[Server]` and system configuration sections, the system configuration overrides the server configuration for that system.
Example:	`LanguageDirectory=./languages`
See Also:	Language StopList

LogRequestTiming

Set LogRequestTiming to True to record the duration times of actions in the logs. This parameter adds timing information to items in all log files that describe actions that have been sent to Answer Server.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	Server
Example:	`LogRequestTiming=True`
See Also:

MaxFileUploadSize

The MaxFileUploadSize parameter specifies the maximum amount of data (in bytes) accepted by the server through an HTTP POST request. This parameter therefore limits the amount of data that can be sent to the server in an ACI action. To specify an unlimited size, set this parameter to -1.

NOTE: OpenText recommends that you do not change the value of this parameter.


Type:	Long
Default:	`10000000`
Required:	No
Configuration Section:	Server
Example:	`MaxFileUploadSize=-1`
See Also:

MaxInputString

The MaxInputString parameter specifies the maximum number of characters that can be sent to the server in an HTTP request string. To specify an unlimited number, set this parameter to -1.


Type:	Long
Default:	`64000`
Required:	No
Configuration Section:	Server
Example:	`MaxInputString=-1`
See Also:

Port

The Port parameter specifies the port that is used to send ACI actions to the ACI server.

You must configure Authorization Roles Configuration Parameters to determine the users that can send actions to the server.


Type:	Long
Default:
Required:	No
Allowed Range:	Minimum: 1 Maximum: 65535
Configuration Section:	Server
Example:	`Port=7008`
See Also:	Authorization Roles Configuration Parameters ProxyClients

PreserveCarriageReturn

Set PreserveCarriageReturn to True to ensure that Answer Server converts literal carriage return bytes to their XML entity equivalent in XML responses. You can use this option for applications where carriage return characters are important, to ensure XML parsers do not convert it to a line feed.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	Server
Example:	`PreserveCarriageReturn=True`
See Also:

ProxyClients

The ProxyClients parameter specifies the IP addresses or host names for proxy clients that are permitted to send actions to the ACI server. Separate multiple addresses with a comma. There must be no space before or after a comma.

When an action is received, if the client address does not appear in any valid authorization roles (see Authorization Roles Configuration Parameters), but it does appear in the ProxyClients parameter, the X-Forwarded-For HTTP header is processed. The header is then used to determine whether the action was forwarded from an authorized client by a trusted Proxy.

If you use a chain of load balancer or proxy components, you must add each IP address to the list in ProxyClients.

The server rejects any request that comes from one of the ProxyClients IP addresses, but that does not contain an X-Forwarded-For HTTP Header that corresponds to an authorized client.

You can use wildcards in the IP addresses. For example, type 187.*.*.* to specify any machine with an IP address that begins with 187. You can also filter the ProxyClients parameter using CIDR notation.


Type:	String
Default:	`...`
Required:	No
Configuration Section:	Server
Example:	A load balancer with IP address 12.34.56.78 forwards query actions from an application server host with IP address 12.34.56.89. For this setup, the configuration is: `[Server] ProxyClients=12.34.56.78 [AuthorizationRoles] 0=QueryRole [QueryRole] StandardRoles=Query Clients=12.34.56.89`
See Also:	Authorization Roles Configuration Parameters

RequireGSSAuth

Set RequireGSSAuth to True to enable GSSAPI authentication mode on the Answer Server ACI port. In this mode, all connections to the ACI port must be authenticated using GSSAPI and the Negotiate HTTP authentication mechanism.

To use GSSAPI authentication, you must also set GSSServiceName, to define the GSSAPI service name that Answer Server must use to identify itself.

NOTE: This method provides an authentication requirement only. OpenText recommends that you use it in conjunction with TLS/SSL to encrypt the authentication data.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	Server
Example:	`RequireGSSAuth=True`
See Also:	GSSServiceName

ReturnRequest

Return your request as part of the response. Set this parameter to True if you want your action response to include a tag containing the original request.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	Server
Example:	`ReturnRequest=True`
See Also:

SSLConfig

Identifies the section of the configuration file in which the SSL configuration details are specified, usually SSLOptionN.

To specify the SSL settings for incoming ACI calls, set this parameter in the [Server] section.


Type:	String
Default:
Required:	No
Configuration Section:	Server, for incoming communication.
Example:	`[Server] SSLConfig=SSLOptions1 ...`
See Also:	SSLCACertificate SSLCertificate SSLCheckCertificate SSLCheckCommonName SSLMethod SSLPrivateKey SSLPrivateKeyPassword

StopList

The stop list to use. This parameter applies only to fact bank and passage extractor systems.

A stop list is a list of very common words, which usually add very little meaning to phrases. For example, in English, the and and can often be ignored without losing the sense of a sentence. Knowledge Discovery uses stop lists to optimize matching.

In a fact bank system, Answer Server uses this stop list to match fact bank codes more broadly. Answer Server attempts to form pseudonym values in the code maps by taking the existing code phrases and removing stop words from the beginning and end of the phrase. Similarly, when Answer Server attempts to match a string to codes, it matches the full phrase, and the phrase with the stop words removed from the beginning and end of the phrase. Answer Server does not attempt to remove stop words from the middle of phrases.

TIP: You might want to use a simpler stop list for fact bank than the full stop list that you use in the Content component, so that it does not remove any useful terms from the code phrases.

In a passage extractor system, Answer Server removes stop words from the classified questions to attempt to find the best match in the data Content component. Answer Server does not use the stop list for question classification, which often depends on common words, such as question words.


Type:	String
Default:
Required:	No
Configuration Section:	Server or MySystem If you configure `StopList` in both the `[Server]` and system configuration sections, the system configuration overrides the server configuration for that system.
Example:	`StopList=English.dat`
See Also:	Language LanguageDirectory

SynonymStore

Answer Server can communicate with a Query Manipulation Server (QMS) and use synonyms to expand queries. This increases the likelihood that Answer Server can find an answer to a question.

This parameter specifies the name of a section in the configuration file that is used to configure the synonym store.


Type:	String
Default:
Required:	Required to use synonyms
Configuration Section:	Server
Example:	`[Server] SynonymStore=SynonymQMS [SynonymQMS] Host=localhost ACIPort=16000`
See Also:	Host ACIPort

Threads

The maximum number of synchronous actions that the server can process simultaneously.

You can calculate the optimum number of threads as follows:

Number of logical CPUs + 1 spare thread.


Type:	Long
Default:	10
Allowed Range:	Minimum: 1 Maximum: 32
Recommended Range:	Minimum: 4 Maximum: 32
Required:	No
Configuration Section:	Server
Example:	`Threads=5`
See Also:

XSLTemplates

The XSLTemplates parameter specifies whether to enable the transformation of ACI action responses using XSL templates.

To transform the response to an action, set this configuration parameter to True, and specify the name of the template in the action. For example:

localhost:1234/action=getstatus&template=MyTemplate


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	Server
Example:	`XSLTemplates=True`
See Also:	TemplateDirectory XSLTemplates (for service actions)

Service Configuration Parameters

This section describes the Service configuration parameters that determine which machines are permitted to use and control a service.

You must enable the service port by specifying the ServicePort configuration parameter, and you must configure authorization roles to determine which users can send service requests (see Authorization Roles Configuration Parameters). The service port then accepts the standard status and control actions described in Service Actions.

Access-Control-Allow-Origin

A list of URLs that you want to use to access the Knowledge Discovery Admin interface. You must configure this parameter to enable Cross Origin Resource Sharing, which allows Knowledge Discovery Admin to access the server's index and service ports.

Each URL must include:

the http:// or https:// prefix
the host that the ACI server is installed on
the ACI port

Separate multiple URLs with spaces.

For example, you can specify different URLs for the local host and remote hosts:

Access-Control-Allow-Origin=http://localhost:9010 http://Computer1.Company.com:9010

Alternatively, you can set Access-Control-Allow-Origin=*, which allows you to access the interface using any valid URL (for example, localhost, a direct IP address, or the host name). The wildcard character (*) is supported only if you do not specify any other entries.


Type:	String
Default:	None
Required:	No
Configuration Section:	Service
Example:	`Access-Control-Allow-Origin=*`
See Also:

ConversationSessionsHeadroom

The number of conversation sessions to request from the License Server when Answer Server starts.

Your Answer Server license includes a certain number of simultaneous conversation sessions, which applies for your whole Knowledge Discovery system as an aggregate license. For example, if your license allows you to have 10 simultaneous sessions, you might have a single Answer Server, which runs up to 10 sessions, or five Answer Servers that run up to two sessions each.

Rather than request a session license seat each time a session starts, Answer Server requests licenses in batches. When it first starts, it requests the number of seats that you specify in ConversationSessionsHeadroom.

As you start conversation sessions on Answer Server, it uses these pre-assigned session license seats until it runs out. When you try to start a session and it does not have any pre-assigned seats available, Answer Server requests a license for the new session from your License Server, along with a new batch of session licenses (the ConversationSessionsHeadroom number of seats).

You can modify the value of ConversationSessionsHeadroom to a suitable value for your license limits and your system. For example, if you have a single Answer Server, you might want to set ConversationSessionsHeadroom to a high value. If you have more Answer Server instances running, you might want to use a lower value, to ensure that one server does not run out of seats while another is not using its whole capacity.

As sessions end and the number of unused licenses in Answer Server increases beyond ConversationsessionsHeadroom, Answer Serverautomatically returns seats to License Server. You can send the GetLicenseInfo action to Answer Server to check how many conversation session seats have been assigned to it, and how many are in use.


Type:	Integer
Default:	5
Required:	No
Configuration Section:	Service
Example:	`ConversationSessionsHeadroom=15`
See Also:

FIPSMode

IMPORTANT: This parameter applies only to the separate FIPS-enabled packages for Red Hat Enterprise Linux (RHEL) 7 and RHEL8 platforms.

For these packages, the components use the system version of OpenSSL (expected to be in the 1.0.x series for RHEL7 and the 1.1.x series for RHEL8). You must download and install these FIPS-enabled components.

For Knowledge Discovery version 13.0 and later, the standard Knowledge Discovery components use OpenSSL3 to provide FIPS 140-2 support on both Windows and Linux. In this case, the FIPSMode parameter has no effect. For information about how to configure these components to enable FIPS, refer to the FIPS Enablement Technical Note.

Set FIPSMode to True to enable the FIPS-compliant cryptographic modules in your Knowledge Discovery components.

Knowledge Discovery uses a cryptographic module which complies with Federal Information Processing Standard 140-2 (FIPS 140-2). This standard defines the technical requirements that Federal Agencies must use for cryptographic-based security systems that protect sensitive or valuable data.

When you use SSL in FIPS mode, all encrypted ACI communication between all Knowledge Discovery components and HTTPS traffic between Knowledge Discovery and third parties (where SSL is supported by the third party) is secured using the FIPS validated OpenSSL Module.

For more information about how to set up and enable FIPS Mode, refer to the FIPS Enablement Technical Note.


Type:	Booolean
Default:	False
Required:	No
Configuration Section:	Service
Example:	`FIPSMode=True`
See Also:

RequireGSSAuth

Set RequireGSSAuth to True to enable GSSAPI authentication mode on the Answer Server service port. In this mode, all connections to the service port must be authenticated using GSSAPI and the Negotiate HTTP authentication mechanism.

To use GSSAPI authentication, you must also set GSSServiceName, to define the GSSAPI service name that Answer Server must use to identify itself.

NOTE: This method provides an authentication requirement only. OpenText recommends that you use it in conjunction with TLS/SSL to encrypt the authentication data.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	Service
Example:	`RequireGSSAuth=True`
See Also:	GSSServiceName

ServiceHost

The host server on which the service is running.

You must configure Authorization Roles Configuration Parameters to determine the users that can send service requests.


Type:	String
Default:	...
Required:	No
Configuration Section:	Service
Example:	`ServiceHost=127.0.0.1`
See Also:	ServicePort

ServicePort

The port on the host server on which the service listens for service status and control requests.

You must configure Authorization Roles Configuration Parameters to determine the users that can send service requests.


Type:	Long
Default:	40010
Required:	Yes
Allowed Range:	Minimum: 1 Maximum: 65535
Recommended Range:	Minimum: 1024 Maximum: 65535
Configuration Section:	Service
Example:	`ServicePort=40010`
See Also:	ServiceHost

SSLConfig

The name of the configuration section that specifies the SSL configuration details (usually SSLOptionN).

Set this parameter in the [Service] section to configure SSL for incoming service actions.


Type:	String
Default:	None
Required:	No
Configuration Section:	Service
Example:	`[Service] SSLConfig=SSLOptions1 ... [SSLOptions1] //SSL options for incoming connections SSLMethod=TLSV1.2 SSLCertificate=host1.crt SSLPrivateKey=host1.key SSLCACertificate=trusted.crt`
See Also:	Secure Socket Layer Parameters

TCPReceiveWindowSize

The TCP receive window size to use when the service receives data (in bytes).

Use this parameter to tune network performance based on bandwidth and client to server round-trip times. Generally, a higher value improves performance in a high-bandwidth, high-delay network, and a lower value improves performance in a low-bandwidth, low-delay network.


Type:	Long
Default:	Determined by the operating system
Allowed Range:	Minimum: 1024 Maximum: 1048576
Required:	No
Configuration Section:	Service
Example:	`TCPReceiveWindowSize=65536`
See Also:

XSLTemplates

The XSLTemplates parameter specifies whether to enable the transformation of ACI action responses using XSL templates.

To transform the response to an action, set this configuration parameter to True, and specify the name of the template in the action. For example:

localhost:1234/action=getstatus&template=MyTemplate


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	Server
Example:	`XSLTemplates=True`
See Also:	TemplateDirectory XSLTemplates (for service actions)

Synonym Store Configuration Parameters

This section describes the configuration parameters that you can use to configure a synonym store.

For more information about using synonyms to expand queries, refer to the Answer Server Administration Guide.

ACIPort

The ACI Port of the Query Manipulation Server (QMS) that provides access to your synonym rules.


Type:	Integer
Default:
Required:	Required to use synonyms
Configuration Section:	Any section that you specify with the parameter SynonymStore
Example:	`[Server] SynonymStore=SynonymQMS [SynonymQMS] Host=localhost ACIPort=16000`
See Also:	Host

Host

The host name or IP address of the Query Manipulation Server (QMS) that provides access to your synonym rules.


Type:	String
Default:
Required:	Required to use synonyms
Configuration Section:	Any section that you specify with the parameter SynonymStore
Example:	`[Server] SynonymStore=SynonymQMS [SynonymQMS] Host=localhost ACIPort=16000`
See Also:	ACIPort

Systems Configuration Parameters

This section describes the configuration parameters that describe the Answer Server systems.

N

The name of the configuration section that contains details of an Answer Server system. List one parameter for each system. The parameter name N must order consecutively from zero.

NOTE: The order in which you specify the systems in the [Systems] section of the configuration file corresponds to the order in which Answer Server attempts to retrieve answers. For example, if you specify a factbank, then an answerbank (see Type), the Ask action retrieves the factual answers first, and then any answers in the answerbank.

You can override this ordering by using the SystemNames parameter for the Ask action.


Type:	String
Default:
Required:	No
Configuration Section:	Systems
Example:	`0=PhoneAnswerBank 1=LaptopAnswerBank 2=PhoneFactBank 3=LaptopFactBank`
See Also:	Type

MySystem Configuration Parameters

This section describes the configuration parameters that control each individual Answer Server system, for example to define the subcomponents that it must connect to.

Type

The type of system that you want to configure. This parameter has the following options:

Answerbank. A system that provides defined answers to a defined set of questions (such as an FAQ). If you create an Answerbank system, you must configure a dedicated Agentstore component to store the questions and question equivalence classes. You define the location of this Agentstore component by setting IDOLHost and IDOLACIPort.
Factbank. A system that provides a simple, factual answer to a question. If you create a Factbank system, you must configure:
- a fact store. You can use a SQL database, or a Lua script as your fact store. Use the ConnectionString parameter if you use a SQL database. Use the ScriptPath and ScriptFunction parameters if you use a Lua fact store.
- the Named Entity Recognition grammars to use for question parsing and time normalization. Use the EductionQuestionGrammars and EductionTimeGrammars parameters.
- the locations of the fact bank coding files, which map entities to codes that Answer Server uses to retrieve facts. Use the CodingsDatPath and CodingsPath parameters.
Passageextractor. A system that extracts relevant answers from documents stored in a Content component. If you create a Passageextractor system, you must configure:
- a Content component that contains documents that Answer Server can extract answers from. Use the IDOLHost and IDOLACIPort parameters.
- a dedicated Agentstore component that contains agents that describe various entity types, such as people and places. Use the AgentstoreHost and AgentstoreACIPort parameters.
- the Named Entity Recognition grammars to use to identify entities in text that might form answers, and to identify sentences and paragraph that might form answers. Use the EductionGrammars parameter.
PassageextractorLLM. A system that uses a Large Language Model (LLM) to extract relevant answers from documents stored in a Content component. If you create a PassageextractorLLM system, you must configure:
- a Content component that contains documents that Answer Server can extract answers from. Use the IDOLHost and IDOLACIPort parameters.
- an LLM module that configures the model that you want to use. Use the ModuleID parameter, and the LLM Module Configuration Parameters.
RAG. A system that uses Retrieval-Augmented Generation (RAG). This system combines relevant information from multiple documents with a configurable prompt, which it passes to a Large Language Model (LLM) to generate a single answer. If you create a RAG system, you must configure:
- a Content component that contains documents that Answer Server can extract answers from. Use the IDOLHost and IDOLACIPort parameters.
- an LLM module that configures the model that you want to use. Use the ModuleID parameter, and the LLM Module Configuration Parameters.
Conversation. A system that runs a conversation task to answer user questions in a real time instant messaging environment. If you create a Conversation system, you must configure:
- a task configuration JSON file that defines the settings for the conversation task. Use the TaskConfigurationFile parameter.
- a dedicated Agentstore component that contains conversation triggers to activate particular conversation tasks based on user input. Use the AgentstoreHost and AgentstoreACIPort parameters.
Remote. A system that runs on a remote Answer Server. When you configure a remote answer system, Answer Server forwards any Ask actions that use the remote system to the associated remote Answer Server. If you create a Remote system, you must configure:
- the location of the remote Answer Server. Use either the AnswerServerHost and AnswerServerACIPort parameters, or set AnswerServer to the name of a configuration section that contains the host and port details for the remote Answer Server (see Remote Answer Server Configuration Parameters).
- the name of the answer system in the remote Answer Server that this remote system must use. Use the AnswerSystem parameter.


Type:	String
Default:
Required:	Yes
Configuration Section:	Systems
Example:	`Type=Answerbank`
See Also:

Answer Bank System Configuration Parameters

This section describes the configuration parameters that you can use in Answer Bank systems (systems where you set Type to AnswerBank).

EductionGrammars

The Named Entity Recognition grammar files that Answer Bank must use for question parsing.

In the Answer Bank system, Answer Server uses Named Entity Recognition to parse incoming questions, and then uses the parsed information to search the Answer Bank for an answer.


Type:	String
Default:
Required:	Required if you want to use contexts with an AnswerBank system with ask; otherwise optional
Configuration Section:	MySystem
Example:	`EductionGrammars=./resources/grammars/question_grammar_en.ecr`
See Also:

EductionLuaScript

The path to the Named Entity Recognition question grammar Lua script.


Type:	String
Default:
Required:	Yes, for `Answerbank` systems where EductionGrammars have been configured
Configuration Section:	MySystem
Example:	`EductionLuaScript=./resources/lua/question_grammar_en.lua`
See Also:

FailedPath

The path to a directory that you want to use to store information for failed index requests to the Answer Bank Agentstore.

This option is available only for Answer Bank systems.


Type:	String
Default:	failed
Required:	No
Configuration Section:	MySystem
Example:	`FailedPath=D:\AnswerServer\failed`
See Also:

IDOLACIPort

The ACI port of the Content component or Agentstore component that the system must connect to. You must also specify the host name or IP address of the machine where the component is installed, by using the IDOLHost parameter.

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

NOTE: If you configure a synonym store, Answer Server can use synonyms to expand queries. To enable synonyms with passage extractor, set this parameter to point to the Query Manipulation Server (QMS) that provides access to your synonyms, and specify the details of the Content component in the QMS configuration file instead.

This parameter is not required for systems where Type is set to FactBank.


Type:	Integer
Default:
Required:	Yes, when Type is set to `AnswerBank`, `PassageExtractor`, `PassageExtractorLLM`, or `RAG`
Configuration Section:	MySystem
Example:	`IDOLACIPort=6000`
See Also:	IDOLHost IDOLSSLConfig

IDOLGSSServiceName

The GSSAPI service name to use for the Content component or Agentstore component that you specify in IDOLHost. If you use the GSSAPI protocol for communication between Answer Server and its subcomponents, this parameter describes the (Kerberos-defined) service name of the Content component or Agentstore component for this system.

IMPORTANT: If you set IDOLGSSServiceName, you must set IDOLHost to a fully qualified domain name (that is, you cannot use localhost, an IP address, or a host without the domain name, even if these values resolve to the correct server). Answer Server retrieves the Kerberos realm from the child server host name.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`IDOLGSSServiceName=CONTENT01`
See Also:	IDOLACIPort IDOLHost

IDOLHost

The host name or IP address of the Content component or Agentstore component that the system must connect to. You must also specify the component ACI port by using the IDOLACIPort parameter.

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.

IMPORTANT: If you set IDOLGSSServiceName, you must set IDOLHost to a fully qualified domain name (that is, you cannot use localhost, an IP address, or a host without the domain name, even if these values resolve to the correct server). Answer Server retrieves the Kerberos realm from the child server host name.


Type:	String
Default:
Required:	Yes, when Type is set to `AnswerBank`, `PassageExtractor` or `PassageExtractorLLM`
Configuration Section:	MySystem
Example:	`IDOLHost=localhost`
See Also:	IDOLACIPort IDOLGSSServiceName IDOLSSLConfig

IDOLSSLConfig

The configuration section in which you specify the configuration details for connecting to the Content component or Agentstore component for this system, usually SSLOptionN. You must set this parameter to use SSL connections between components.

This parameter configures the SSL connection to the component that you configure by using IDOLACIPort and IDOLHost.

NOTE: Answer Server uses the same SSL configuration for ACI and indexing requests to the Content or Agentstore.

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`IDOLSSLConfig=SSLOption2`
See Also:	IDOLACIPort IDOLHost Secure Socket Layer Parameters

MinScore

The minimum score that an answer from this system must have to return as a result for the Ask action.


Type:	Number
Default:	0
Allowed Range:	Minimum: 0 Maximum: 100
Required:	No
Configuration Section:	MySystem
Example:	`MinScore=60`
See Also:	Ask action MinScore action parameter

PopularityWindowDays

The number of days that you want to consider popularity information for your question equivalence classes. This parameter applies only when Type is set to answerbank.

When you configure StatsStorage, Answer Server sends statistics to your statistics database each time the text of an Ask action matches the rule for a question equivalence class. It stores the popularity information for the question equivalence classes.

Periodically, Answer Server also requests the popularity information and uses it to populate a usage count field in the question equivalence class, in the Answer Bank Agentstore component. PopularityWindowDays specifies the number of days of information that Answer Server requests from the database. For example, the default value requests information from the last week, and updates the usage count field with the number of matches in the last week.

The database does not expire the data after this amount of time, so you can increase the value of PopularityWindowDays, and Answer Server requests and updates the count information accordingly.


Type:	Integer
Default:	7
Required:	No
Configuration Section:	MySystem
Example:	`PopularityWindowDays=31`
See Also:

QueuePath

The path to a directory that you want to use to store the Answer Server outgoing index queue information. This parameter applies only when Type is set to answerbank.

Answer Bank uses this directory to store queued index requests that it forwards to the Answer Bank Agentstore component.


Type:	String
Default:	outgoing
Required:	No
Configuration Section:	MySystem
Example:	`QueuePath=D:\AnswerServer\queue`
See Also:

SpellcheckEngine

The name of a section in the configuration file, in which you set the parameters that are required to check spelling.

The spelling checker is used as follows:

AnswerBank systems - Answer Server checks any rules that you send to the TestRule action. A correction might be returned in the response, in the element spellchecked_rule. This correction is not used by the Answer Bank system (Answer Server always uses the rule that you supply), but if appropriate you can resend the action with the corrected rule.
Conversation systems - When a user submits input that does not trigger any tasks, Answer Server runs the spelling checker. If a spelling correction is possible and that correction would trigger one or more tasks, the user is presented with the suggested correction and a list of matching tasks through the standard disambiguation prompt.


Type:	String
Default:
Required:	Required to check spelling
Configuration Section:	MySystem
Example:	`SpellcheckEngine=MySpellingChecker [MySpellingChecker] Type=Content Host=localhost ACIPort=12345 LanguageType=englishUTF8`
See Also:	Spelling Checker Configuration Parameters

StatsStorage

The name of the configuration section that you use to define connection details for a statistics storage database. This parameter applies only when Type is set to answerbank.

You can configure Answer Server to send statistics about the popularity of particular questions to an ODBC-combatible database. If you configure StatsStorage, and the appropriate connection information for the database, Answer Server sends information to the database about the question equivalence classes that match questions that your users send in the Ask action text.

The database stores the popularity information. Periodically, Answer Server also queries the database for information about the popularity of the question equivalence classes, and adds this information to a field in the question equivalence class. Answer Server can use this field to sort question equivalence classes by popularity in the GetResources action.

You can configure how often Answer Server updates the popularity field in the question equivalence classes by setting UpdatePopularityInterval. You can also configure the number of days of statistics that Answer Server considers when retrieving popularity information by setting PopularityWindowDays.

The database that you configure must exist, but Answer Server creates all the tables that it needs to store the statistics information.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`StatsStorage=MyStatsDB`
See Also:	UpdatePopularityInterval PopularityWindowDays MyStatisticsDB Configuration Parameters

TempDirectory

The path to a directory that you want to use to store the Answer Server temporary files that it generates during indexing. This parameter applies only when Type is set to answerbank.

Answer Bank uses this directory to store temporary files that it generates for index requests that it sends to the Answer Bank Agentstore component.


Type:	String
Default:	indextemp
Required:	No
Configuration Section:	MySystem
Example:	`TempDirectory=D:\AnswerServer\indextemp`
See Also:

UndeleteLifetime

The minimum amount of time (in seconds) after deletion that a question or question equivalence class is available to undelete. This parameter is applicable only for systems that have Type set to Answerbank.

When you delete a question or question equivalence class, Answer Server uses ExpireDateType fields in the Answer Bank Agentstore component to manage the expiration of deleted items.

To change the expiration time that Answer Server assigns to deleted items, modify UndeleteLifetime for your Answer Bank system.

To update the expiration schedule, you must modify the Answer Bank Agentstore configuration. Refer to the Content Component Help.


Type:	Number
Default:	600
Allowed Range	Minimum: 10
Required:	No
Configuration Section:	MySystem
Example:	`UndeleteLifetime=1200`
See Also:

UpdateLikelihoodInterval

The number of seconds between updates of the answer likelihood score field in the questions in your Answer Bank Agentstore. This parameter applies only when you set Type to answerbank.

The answer likelihood score field for a particular question stores the likelihood that there is an existing answer in your question equivalence classes. Answer Server uses the question to query your question equivalence classes, and uses the relevance score of each question equivalence class in the query to calculate the likelihood score.

You can use this score to sort questions by the likelihood in the GetResources action.

Periodically, Answer Server runs a background process to calculate the likelihood scores for all questions in the Answer Bank Agentstore that do not have an answer, and updates the field in those questions. UpdateLikelihoodInterval specifies how often you want to update the score field.


Type:	Integer
Default:	600
Allowed Range:	Minimum: 10
Required:	No
Configuration Section:	MySystem
Example:	`UpdateLikelihoodInterval=1800`
See Also:

UpdatePopularityInterval

The number of seconds between updates of the question popularity field in the Answer Bank Agentstore. This parameter applies only when you set Type to answerbank.

Answer Server uses the value of this field to sort question equivalence classes by popularity in the GetResources action.

You can update the field more frequently if you need up-to-date information to sort by popularity. However, for performance reasons OpenText recommends that you do not update the popularity count field too frequently, because it might result in a large number of indexing operations in the Answer Bank Agentstore component.

NOTE: If you disable the statistics database or it does not exist, all question equivalence classes in your Answer Bank agentstore have a usage count of zero.


Type:	Integer
Default:	600
Allowed Range:	Minimum: 10
Required:	No
Configuration Section:	MySystem
Example:	`UpdatePopularityInterval=60`
See Also:

Conversation System Configuration Parameters

This section describes the configuration parameters that you can use only in Conversation systems (systems where you set Type to Conversation).

AgentstoreACIPort

The ACI port of the Agentstore component that contains the agents that describe entity types. You must also specify the host name or IP address of the machine where the component is installed, by using the AgentstoreHost parameter.

This parameter is required for systems where Type is set to passageextractor or conversation.


Type:	Integer
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AgentstoreACIPort=7000`
See Also:	AgentstoreHost AgentstoreSSLConfig

AgentstoreGSSServiceName

The GSSAPI service name to use to connect to the Agentstore component that you specify in AgentstoreHost. If you use the GSSAPI protocol for communication between Answer Server and its subcomponents, this parameter describes the (Kerberos-defined) service name of the Passage Extractor Agentstore component for this system.

IMPORTANT: If you set AgentstoreGSSServiceName, you must set AgentstoreHost to a fully qualified domain name (that is, you cannot use localhost, an IP address, or a host without the domain name, even if these values resolve to the correct server). Answer Server retrieves the Kerberos realm from the child server host name.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AgentstoreGSSServiceName=AGENT02`
See Also:	AgentstoreACIPort AgentstoreHost

AgentstoreHost

The host name or IP address of the Agentstore component that contains the agents that describe entity types. You must also specify the component ACI port by using the AgentstoreACIPort parameter.

This parameter is required to systems where Type is set to passageextractor or conversation.

IMPORTANT: If you set AgentstoreGSSServiceName, you must set AgentstoreHost to a fully qualified domain name (that is, you cannot use localhost, an IP address, or a host without the domain name, even if these values resolve to the correct server). Answer Server retrieves the Kerberos realm from the child server host name.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AgentstoreHost=localhost`
See Also:	AgentstoreACIPort AgentstoreGSSServiceName AgentstoreSSLConfig

AgentstoreReferenceField

The name of the document field in your Agent trigger documents that contains the ID of the conversation task that you want to run. By default, Answer Server uses the document reference.

For example, if you use an Agentstore component that contains category information, you can choose whether to use the category name (the autn:title field) as the conversation task name, rather than the category ID (the autn:reference field).


Type:	String
Default:	`autn:reference`
Required:	No
Configuration Section:	MySystem
Example:	`AgentstoreReferenceField=autn:title`
See Also:

AgentstoreSSLConfig

The configuration section in which you specify the configuration details for connecting to the passage extractor Agentstore component for this system, usually SSLOptionN. You must set this parameter to use SSL connections between components.

This parameter configures the SSL connection to the component that you configure by using AgentstoreACIPort and AgentstoreHost.

NOTE: Answer Server uses the same SSL configuration for ACI and indexing requests to the Agentstore component.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AgentstoreSSLConfig=SSLOption2`
See Also:	AgentstoreACIPort AgentstoreHost Secure Socket Layer Parameters

AgentTriggerDefaults

The name of a configuration section where you set values for query parameters to use when the conversation task sends queries to the conversation Agentstore.

When you set this parameter, you must also create a configuration section with this name.

In this section, you can set any Content component query parameters, and set a value that Answer Server must use when sending agent trigger queries to the Agentstore.

For example, you might want to configure the DatabaseMatch parameter to set it to a particular database in your Agentstore.

This configuration section allows you to override the default values for the Agentstore query parameters.

For more information about the query parameters, refer to the Content Component Help.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AgentTriggerDefaults=MyAgentTriggerParams [MyAgentTriggerParams] DatabaseMatch=MyAgentDB`
See Also:

SessionExpirationIdleTime

The number of seconds that a conversation session can be idle for before it expires.

Answer Server runs an expiration operation regularly every SessionExpirationInterval. When a session has been idle for longer than the specified idle time when the expiration operation runs, the session expires.

If a user attempts to interact with an expired session, it returns an error.


Type:	Integer
Default:	300
Allowed Range:	Minimum: 10
Required:	No
Configuration Section:	MySystem
Example:	`SessionExpirationIdleTime=600`
See Also:

SessionExpirationInterval

The number of seconds between each scan of current conversation sessions to find any that have expired. You specify the length of time that a session must be idle before it expires by setting SessionExpirationIdleTime.

Set SessionExpirationInterval to zero (0) if you do not want to expire sessions.


Type:	Integer
Default:	60
Required:	No
Configuration Section:	MySystem
Example:	`SessionExpirationInterval=60`
See Also:

SpellcheckEngine

The name of a section in the configuration file, in which you set the parameters that are required to check spelling.

The spelling checker is used as follows:

AnswerBank systems - Answer Server checks any rules that you send to the TestRule action. A correction might be returned in the response, in the element spellchecked_rule. This correction is not used by the Answer Bank system (Answer Server always uses the rule that you supply), but if appropriate you can resend the action with the corrected rule.
Conversation systems - When a user submits input that does not trigger any tasks, Answer Server runs the spelling checker. If a spelling correction is possible and that correction would trigger one or more tasks, the user is presented with the suggested correction and a list of matching tasks through the standard disambiguation prompt.


Type:	String
Default:
Required:	Required to check spelling
Configuration Section:	MySystem
Example:	`SpellcheckEngine=MySpellingChecker [MySpellingChecker] Type=Content Host=localhost ACIPort=12345 LanguageType=englishUTF8`
See Also:	Spelling Checker Configuration Parameters

TaskConfigurationFile

A comma-separated list of conversation task configuration JSON files that you want to use for this conversation system. For each JSON file, specify the path and file name.

The conversation configuration file contains various settings for the conversation task. Each task must have an ID. The task can also include:

a trigger to specify when a particular task must run.
an initial response to return at the start of the task.
a list of requirements (that is, information that the task requires to complete an action, such as the name of a user or contact information).
the details of one or more Lua functions to run when the task requirements are satisfied.
information about other tasks that the task must route to when certain conditions are met.

You can split the configuration information up into multiple JSON files to make it easier to maintain the files. Answer Server merges the configurations together when it runs.

For more information about task configuration files, refer to the Answer Server Administration Guide.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`TaskConfigurationFile=C:\AnswerServer\Conversations\conversation_tasks.json`
See Also:

Fact Bank System Configuration Parameters

This section describes the configuration parameters that you can use in Fact Bank systems (systems where you set Type to FactBank).

AskParallelizationFactor

The number of threads that Answer Server should use to gather answers. Increasing the value of this parameter can improve the response time because the different interpretations of the question can be split between the available threads.

This parameter specifies the number of threads to use to gather answers for each ask action, so if you set AskParallelizationFactor=2 and process four ask actions concurrently, Answer Server uses eight threads to gather answers.


Type:	Integer
Default:	1
Allowed Range:	Maximum: 32
Required:	No
Configuration Section:	MySystem
Example:	`AskParallelizationFactor=4`
See Also:

BackendType

The type of back end you want to use for the fact store component. This parameter is used only for systems that have Type set to Factbank.

You can use one of the following values:

sqldb. Use an SQL database. In this case, you must also set ConnectionString to the connection string to use to connect to the fact store database.
lua. Use a custom Lua script. In this case, you must also set ScriptPath to specify the Lua script that you want to use, and you can optionally set ScriptFunction to the name of the entry function that Answer Server must call.

For all backends, you must configure the question parser Named Entity Recognition grammars by using the EductionQuestionGrammars and EductionTimeGrammars parameters, and configure the coding files by using the CodingsDatPath and CodingsPath parameters.


Type:	String
Default:
Required:	Yes, for `Factbank` systems.
Configuration Section:	MySystem
Example:	`BackendType=sqldb`
See Also:

CodifierType

The method to use to store coding information for your Fact Bank. You can use one of the following options:

Files. Use coding text files. For this option, you must create the coding files and set CodingsPath and CodingsDatPath to the locations of your coding files.
odbc. Use a SQL database. For this option, you must set have a coding SQL database, and set CodingsConfigSection to the name of a configuration section that contains the database connection information.


Type:	String
Default:	Files
Required:	No
Configuration Section:	MySystem
Example:	`CodifierType=odbc`
See Also:	CodingsDatPath CodingsPath CodingsConfigSection

CodingsConfigSection

The name of the configuration section where you define your coding database. This parameter applies only to Fact Bank systems that have CodifierType set to odbc.

For more information about how to create the coding database, refer to the Answer Server Administration Guide.


Type:	String
Default:	Files
Required:	No
Configuration Section:	MySystem
Example:	`CodingsConfigSection=FactBankCodings`
See Also:	Fact Bank Coding Database Configuration Parameters

CodingsDatPath

The path to the directory that contains the optimized codings files. This parameter is required for a system that has Type set to Factbank.

The coding files contain a list of entities and properties that map to a particular code. Answer Server uses coding maps to ensure that equivalent forms of an entity match the same results. For example, you can map President of the United States and POTUS to the same code, so that the correct answer can be retrieved regardless of how the user specifies it in the question.

CodingsDatPath specifies the directory that Answer Server uses to store the optimized .dat file versions of the coding files. Answer Server generates these files from the .txt files when it starts up to improve the performance of reading the coding files.

For more information about how to create the coding files for your fact bank, refer to the Answer Server Administration Guide.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`CodingsDatPath=./codings`
See Also:	CodingsPath

CodingsPath

The path to the directory that contains the plain text codings files. This parameter is required for a system that has Type set to Factbank.

CodingsPath specifies the directory that contains the plain text (human-readable) version of the coding file. When you start Answer Server, the server uses these plain text files to generate optimized .dat files to improve performance.

The directory that you specify must contain files with the following names and contents:

code_to_entity.txt
code_to_property.txt
property_to_code.txt
entity_to_code.txt

Answer Server creates the optimized .dat files with the same base name as these files (code_to_entity.dat and so on).

For more information about how to create the coding files for your fact bank, refer to the Answer Server Administration Guide.


Type:	String
Default:
Required:	Yes, for `Factbank` systems.
Configuration Section:	MySystem
Example:	`CodingsPath=./codings`
See Also:	CodingsDatPath

ConnectionString

The connection string to use to connect to the fact store SQL database. This parameter is required for a Fact Bank system when you have set BackendType to sqldb.

The connection string is passed on to the database, so you can use a connection string that works with any SQL client application.

NOTE: On Linux operating systems, remove the spaces in the connection string.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`ConnectionString=Driver={PostgreSQL};Server=sql-host.mycompany.com;Port=5432;Database=factstoredb;Uid=postgres;password=password;`
See Also:	BackendType

EductionEntities

The Named Entity Recognition entities to use for question parsing. Answer Server uses these entities when it sends requests to the Question Parser.

By default, Answer Server uses all the entities that you have included in your Answer Server installation. To improve performance, you can use this parameter to use only specified entities. This option reduces the number of entities that Named Entity Recognition attempts to match.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`EductionEntities=factbank*`
See Also:	TimeEntities

EductionQuestionGrammars

The Named Entity Recognition grammar files that Fact Bank must use for question parsing. This parameter applies only when Type is set to factbank.

In the Fact Bank system, Answer Server uses Named Entity Recognition to parse incoming questions to find the entities and qualifiers that define the question, and then uses the parsed information to search the fact store for an answer.

You might also want to set EductionTimeGrammars to specify grammars to use for time normalization.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`EductionQuestionGrammars=./resources/grammars/question_grammar_en.ecr`
See Also:	EductionTimeGrammars

EductionLuaScript

The path to the Named Entity Recognition question grammar Lua script.


Type:	String
Default:
Required:	Yes, for `Factbank` systems.
Configuration Section:	MySystem
Example:	`EductionLuaScript=./resources/lua/question_grammar_en.lua`
See Also:

EductionTimeGrammars

The Named Entity Recognition grammar files that Fact Bank must use for advanced time normalization. This parameter applies only when Type is set to factbank.

Answer Server uses these grammars to extract dates and times in various formats from questions and normalize them to a consistent format, to improve fact retrieval. This process is not part of the main question parsing operation.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`EductionTimeGrammars=./resources/grammars/datetime_processing.ecr`
See Also:	TimeEntities

IDOLACIPort

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.


Type:	Integer
Default:
Required:	Yes, when Type is set to `AnswerBank`, `PassageExtractor`, `PassageExtractorLLM`, or `RAG`
Configuration Section:	MySystem
Example:	`IDOLACIPort=6000`
See Also:	IDOLHost IDOLSSLConfig

IDOLGSSServiceName


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`IDOLGSSServiceName=CONTENT01`
See Also:	IDOLACIPort IDOLHost

IDOLHost

The host name or IP address of the Content component or Agentstore component that the system must connect to. You must also specify the component ACI port by using the IDOLACIPort parameter.

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.


Type:	String
Default:
Required:	Yes, when Type is set to `AnswerBank`, `PassageExtractor` or `PassageExtractorLLM`
Configuration Section:	MySystem
Example:	`IDOLHost=localhost`
See Also:	IDOLACIPort IDOLGSSServiceName IDOLSSLConfig

IDOLSSLConfig

This parameter configures the SSL connection to the component that you configure by using IDOLACIPort and IDOLHost.

NOTE: Answer Server uses the same SSL configuration for ACI and indexing requests to the Content or Agentstore.

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`IDOLSSLConfig=SSLOption2`
See Also:	IDOLACIPort IDOLHost Secure Socket Layer Parameters

Language

The language to use for stemming. This parameter applies only to fact bank and passage extractor systems.

Answer Server uses stemming for fact bank and passage extractor to improve question parsing and answer matching.

Answer Server supports the same languages for stemming as the Content component. For more information, refer to Knowledge Discovery Expert.


Type:	String
Default:	English
Required:	No
Configuration Section:	Server or MySystem If you configure `Language` in both the `[Server]` and system configuration sections, the system configuration overrides the server configuration for that system.
Example:	`Language=French`
See Also:	LanguageDirectory StopList

LanguageDirectory

The directory that contains any language files (such as the stop list file).


Type:	String
Default:	Answer Server working directory
Required:	No
Configuration Section:	Server or MySystem If you configure `LanguageDirectory` in both the `[Server]` and system configuration sections, the system configuration overrides the server configuration for that system.
Example:	`LanguageDirectory=./languages`
See Also:	Language StopList

MinScore

The minimum score that an answer from this system must have to return as a result for the Ask action.


Type:	Number
Default:	0
Allowed Range:	Minimum: 0 Maximum: 100
Required:	No
Configuration Section:	MySystem
Example:	`MinScore=60`
See Also:	Ask action MinScore action parameter

ScriptFunction

The entry function that Answer Server must use when it calls the Fact Bank script.

By default, when Answer Server processes an Ask action that includes the Lua Fact Bank, it calls the configured script (see ScriptPath), and calls the fetch entry function. If you want to use a different name for your entry function, set ScriptFunction to the new name.


Type:	String
Default:	fetch
Required:	No
Configuration Section:	MySystem
Example:	`ScriptFunction=fetch`
See Also:	ScriptPath

ScriptPath

The path to the Lua script that you want to use as your Fact Bank. Answer Server calls out to this script whenever it processes an Ask action that includes the Lua Fact Bank system, and returns the response as an answer.

You can also configure ScriptFunction to specify the entry function that Answer Server must call in your script.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`ScriptPath=./scripts/factretriever.lua`
See Also:	ScriptFunction

SQLLimit

The maximum number of facts that Answer Server retrieves from the SQL fact store during an Ask action.

When your fact store is large, setting this option can significantly reduce the time that certain queries take. However, it might also result in Answer Server missing some valid results, which might reduce the accuracy for some broadly-defined questions.

Answer Server always attempts to retrieve only the relevant facts from the fact store, so this setting typically does not affect the accuracy of results for precise questions.


Type:	String
Default:	0 (no limit)
Required:	No
Configuration Section:	MySystem
Example:	`SQLLimit=100000`
See Also:

StopList

The stop list to use. This parameter applies only to fact bank and passage extractor systems.

TIP: You might want to use a simpler stop list for fact bank than the full stop list that you use in the Content component, so that it does not remove any useful terms from the code phrases.


Type:	String
Default:
Required:	No
Configuration Section:	Server or MySystem If you configure `StopList` in both the `[Server]` and system configuration sections, the system configuration overrides the server configuration for that system.
Example:	`StopList=English.dat`
See Also:	Language LanguageDirectory

TimeEntities

The Named Entity Recognition entities to use to extract time and date information from questions for time normalization. If you also set EductionTimeGrammars, TimeEntities specifies the entities in the specified grammar files.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`TimeEntities=date*`
See Also:	EductionQuestionGrammars EductionTimeGrammars

TimeLuaScript

The path to the Named Entity Recognition time parsing grammar Lua script.


Type:	String
Default:
Required:	Yes, for `Factbank` systems.
Configuration Section:	MySystem
Example:	`TimeLuaScript=./resources/lua/datetime.lua`
See Also:

Fact Bank Coding Database Configuration Parameters

This section describes the configuration parameters that you can use to set up the database for coding files in Fact Bank systems.

####### CacheExpirationInterval

The number of seconds to keep entries in the codings cache. This parameter applies only when CodifierType is odbc.

Answer Server uses a cache to improve Fact Bank performance when looking up codings. You can use this parameter to ensure that Fact Bank regularly rechecks the database for new and updated entries. When Answer Server finds an entry in the cache that is older than the specified number of seconds, it expires it and reloads it from the database.

You can also optionally set CacheNotFoundExpirationInterval to define a separate expiration time for entries in the cache corresponding to coding values that were not found in the database.

You can also manually reload the codings cache by using the ManageResources action.


Type:	String
Default:	none (cache entries expire only when the cache runs out of allocated space)
Required:	No
Configuration Section:	MyCodingsConfig
Example:	`CacheExpirationInterval=86400`
See Also:	CodifierType CacheNotFoundExpirationInterval

####### CacheNotFoundExpirationInterval

The number of seconds to keep entries in the codings cache for codings that were not found on lookup. This parameter applies only when CodifierType is odbc.

Answer Server uses a cache to improve Fact Bank performance when looking up codings. When it cannot find an item in the database, it stores a not found entry in the cache so that it does not make repeated unsuccessful look-ups.

You can use this parameter with CacheExpirationInterval to ensure that Fact Bank regularly rechecks the database for new entries. When Answer Server finds a not found entry in the cache that is older than the specified number of seconds, it expires it and reloads it from the database.

You might want to set CacheNotFoundExpirationInterval to be more frequent than CacheExpirationInterval if you are adding new values to your codings database more frequently than updating the existing values.

If you do not set CacheNotFoundExpirationInterval, Answer Server uses the value of CacheExpirationInterval for all cache entries.

You can also manually reload the codings cache by using the ManageResources action.


Type:	String
Default:	CacheExpirationInterval
Required:	No
Configuration Section:	MyCodingsConfig
Example:	`CacheExpirationInterval=43200`
See Also:	CodifierType CacheExpirationInterval

####### ConnectionString

The connection string to use to connect to the coding SQL database. You must set this parameter in the coding configuration section when you have set CodifierType to odbc for one or more of your Fact Bank systems.

The connection string is passed on to the database, so you can use a connection string that works with any SQL client application.

NOTE: On Linux operating systems, remove the spaces in the connection string.


Type:	String
Default:
Required:	No
Configuration Section:	MyCodingsConfig
Example:	`ConnectionString=Driver={PostgreSQL};Server=sql-host.mycompany.com;Port=5432;Database=codingsdb;Uid=postgres;password=password;`
See Also:	CodifierType

Passage Extractor System Configuration Parameters

This section describes the configuration parameters that you can use in Passage Extractor systems (systems where you set Type to PassageExtractor).

ACIMaxResults

The maximum number of results that Answer Server requests from the data Content component. This parameter applies only when Type is set to PassageExtractor, PassageExtractorLLM or RAG.

A higher value can improve the results that you get from the passage extractor system, but can also result in higher query times. OpenText recommends that you test different values in your answer system to find the appropriate balance between accuracy and performance.


Type:	Integer
Default:	12
Required:	No
Configuration Section:	MySystem
Example:	`ACIMaxResults=15`
See Also:

AgentstoreACIPort

This parameter is required for systems where Type is set to passageextractor or conversation.


Type:	Integer
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AgentstoreACIPort=7000`
See Also:	AgentstoreHost AgentstoreSSLConfig

AgentstoreGSSServiceName


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AgentstoreGSSServiceName=AGENT02`
See Also:	AgentstoreACIPort AgentstoreHost

AgentstoreHost

The host name or IP address of the Agentstore component that contains the agents that describe entity types. You must also specify the component ACI port by using the AgentstoreACIPort parameter.

This parameter is required to systems where Type is set to passageextractor or conversation.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AgentstoreHost=localhost`
See Also:	AgentstoreACIPort AgentstoreGSSServiceName AgentstoreSSLConfig

AgentstoreSSLConfig

This parameter configures the SSL connection to the component that you configure by using AgentstoreACIPort and AgentstoreHost.

NOTE: Answer Server uses the same SSL configuration for ACI and indexing requests to the Agentstore component.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AgentstoreSSLConfig=SSLOption2`
See Also:	AgentstoreACIPort AgentstoreHost Secure Socket Layer Parameters

AnswerCandidateEmbeddingsSettings

The name of a configuration section that contains settings for how Answer Server queries the Content component for vectors. This parameter applies only when Type is set to PassageExtractor, PassageExtractorLLM. or RAG.

You can use this option as an alternative to the default conceptual search, if you have vector search configured in your Content component. In a RAG system, you can use a combination of vector and conceptual search, by setting RetrievalType to mixed.

You must create the corresponding configuration section, and configure VectorField and EmbeddingsConfig. See My Vector Settings Configuration Parameters.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AnswerCandidateEmbeddingsSettings=VectorSettings [VectorSettings] EmbeddingsConfig=EmbeddingsSystem VectorField=VECTORA`
See Also:

CandidateRetrievalDefaults

The name of a configuration section that contains details of parameter values to use for passage extractor queries. This parameter applies only when Type is set to PassageExtractor, PassageExtractorLLM or RAG.

Answer Server sends queries to the data Content component to retrieve candidate answers. You can use this option to set particular parameters for these queries, for example to query only a particular set of databases.

Set CandidateRetrievalDefaults to the name of a configuration section. You must create a configuration section with this name. The configuration section can contain any valid Content component Query parameter. When Answer Server sends candidate retrieval queries to the configure Content component, it uses these parameter values.

NOTE: You can also set parameters that you want to set in your queries by using the AllowedQueryParameters parameter. This option lists parameters that Answer Server must pass through from the action it receives to the queries that it sends to other components.

If you set one of these allowed parameters in a query, Answer Server uses the query value, rather than the value in the CandidateRetrievalDefaults configuration. You can use the CandidateRetrievalDefaults configuration to set default values, which you can override in particular queries as required.

For more information about the Content component Query action parameters, refer to the Content Component Help.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`CandidateRetrievalDefaults=CandidateRetrievalParams [CandidateRetrievalParams] DatabaseMatch=MyAnswersDB`
See Also:	AllowedQueryParameters

CandidateRetrievalOperator

The query operator to use between terms in passage extractor queries. This parameter applies only when Type is set to PassageExtractor, PassageExtractorLLM, or RAG.

By default, Answer Server sends queries to the data Content component with a space character between the query terms. Set CandidateRetrievalOperator if you want to use a different operator between terms.

In general, OpenText recommends that you use the default value.


Type:	String
Default:	space
Required:	No
Configuration Section:	MySystem
Example:	`CandidateRetrievalOperator=+`
See Also:	AllowedQueryParameters

ClassifierBehaviorFile

The location and name of the Passage Extractor classifier behavior file. This parameter applies only when Type is set to PassageExtractor or PassageExtractorLLM.

The primary classification is determined by a probability threshold, which is 0.85 by default.

If you move or rename the classification behavior JSON file, set ClassifierBehaviorFile to the new name and location.

You can also modify the contents of the file for your system, for example if you want to change the probability thresholds or use your own classification labels. You can retrieve the JSON schema by sending the GetResources action with Type set to schema.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`ClassifierBehaviorFile=./passageextractor/configuration/classifier_behavior.json`
See Also:	ClassifierFile LabelFile

ClassifierFile

The location and name of the Passage Extractor classifier file. This parameter applies only when Type is set to PassageExtractor or PassageExtractorLLM.

Answer Server uses the classifier and label files to save the trained question classifiers. The question classifiers describe the types of different questions. For PassageExtractor systems, this determines what entities (if any) to extract from candidate answers.

At startup, the question classifier uses the classifier file at this location, if it exists, or it saves the trained classifier resources to this location.

The question classifier is required by Passage Extractor. If you do not set ClassifierFile, you cannot save the question classifier, and must retrain one each time you restart Answer Server. To save the classifier, you must also set LabelFile.


Type:	String
Default:
Required:	Yes, when Type is set to `PassageExtractor` or `PassageExtractorLLM`
Configuration Section:	MySystem
Example:	`ClassifierFile=./passageextractor/classifiertraining/svm_en.dat`
See Also:	LabelFile

EductionGrammars

The Named Entity Recognition grammar files that Passage Extractor must use for entity extraction. This parameter applies only when Type is set to PassageExtractor.

In the Passage Extractor system, Answer Server uses these Named Entity Recognition grammars to identify the entities in text that might form legitimate answers. It also identifies sentences and paragraphs that might form legitimate answers, by using pattern matching.


Type:	String
Default:
Required:	Yes, when Type is set to `PassageExtractor`
Configuration Section:	MySystem
Example:	`EductionGrammars= ./resources/grammars/question_grammar_en.ecr, ./passageextractor/grammars/number_en.ecr, ./passageextractor/grammars/person_en.ecr, ./passageextractor/grammars/date_en.ecr, ./passageextractor/grammars/money_en.ecr`
See Also:

EntityExtractionFile

The path to the Passage Extractor entity extraction file. This parameter applies only when Type is set to PassageExtractor.

The entity extraction file contains details of the components that Passage Extractor can use to extract different types of entities. This file relates the question classifications that you use to train a question classifier to the entities that you manage in Named Entity Recognition or the Agentstore component.

If you move or rename the entity extraction JSON file, set EntityExtractionFile to the new name and location.

You can also modify the contents of the file for your system, for example if you add Agent entity files that you want Passage Extractor to use. For more information, refer to the Answer Server Administration Guide.


Type:	String
Default:
Required:	Yes, when Type is set to `PassageExtractor`
Configuration Section:	MySystem
Example:	`EntityExtractionFile=./passageextractor/configuration/entity_extraction_en.json`
See Also:

IDOLACIPort

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.


Type:	Integer
Default:
Required:	Yes, when Type is set to `AnswerBank`, `PassageExtractor`, `PassageExtractorLLM`, or `RAG`
Configuration Section:	MySystem
Example:	`IDOLACIPort=6000`
See Also:	IDOLHost IDOLSSLConfig

IDOLGSSServiceName


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`IDOLGSSServiceName=CONTENT01`
See Also:	IDOLACIPort IDOLHost

IDOLHost

The host name or IP address of the Content component or Agentstore component that the system must connect to. You must also specify the component ACI port by using the IDOLACIPort parameter.

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.


Type:	String
Default:
Required:	Yes, when Type is set to `AnswerBank`, `PassageExtractor` or `PassageExtractorLLM`
Configuration Section:	MySystem
Example:	`IDOLHost=localhost`
See Also:	IDOLACIPort IDOLGSSServiceName IDOLSSLConfig

IDOLSSLConfig

This parameter configures the SSL connection to the component that you configure by using IDOLACIPort and IDOLHost.

NOTE: Answer Server uses the same SSL configuration for ACI and indexing requests to the Content or Agentstore.

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`IDOLSSLConfig=SSLOption2`
See Also:	IDOLACIPort IDOLHost Secure Socket Layer Parameters

LabelFile

The location and name of the Passage Extractor classifier label file. This parameter applies only when Type is set to PassageExtractor or PassageExtractorLLM.

Answer Server uses the classifier and label files to save the trained question classifiers. The question classifiers describe the types of different questions, and therefore what entities (if any) to extract from candidate answers.

At startup, the question classifier uses the label file at this location, if it exists, or it saves the trained classifier resources to this location.

The question classifier is required. If you do not set LabelFile, you cannot save the question classifier, and must retrain one each time you restart Answer Server. To save the classifier, you must also set ClassifierFile.


Type:	String
Default:
Required:	Yes, when Type is set to `PassageExtractor` or `PassageExtractorLLM`
Configuration Section:	MySystem
Example:	`LabelFile=./passageextractor/classifiertraining/labels_en.dat`
See Also:	ClassifierFile

Language

The language to use for stemming. This parameter applies only to fact bank and passage extractor systems.

Answer Server uses stemming for fact bank and passage extractor to improve question parsing and answer matching.

Answer Server supports the same languages for stemming as the Content component. For more information, refer to Knowledge Discovery Expert.


Type:	String
Default:	English
Required:	No
Configuration Section:	Server or MySystem If you configure `Language` in both the `[Server]` and system configuration sections, the system configuration overrides the server configuration for that system.
Example:	`Language=French`
See Also:	LanguageDirectory StopList

LanguageDirectory

The directory that contains any language files (such as the stop list file).


Type:	String
Default:	Answer Server working directory
Required:	No
Configuration Section:	Server or MySystem If you configure `LanguageDirectory` in both the `[Server]` and system configuration sections, the system configuration overrides the server configuration for that system.
Example:	`LanguageDirectory=./languages`
See Also:	Language StopList

MinScore

The minimum score that an answer from this system must have to return as a result for the Ask action.


Type:	Number
Default:	0
Allowed Range:	Minimum: 0 Maximum: 100
Required:	No
Configuration Section:	MySystem
Example:	`MinScore=60`
See Also:	Ask action MinScore action parameter

StopList

The stop list to use. This parameter applies only to fact bank and passage extractor systems.

TIP: You might want to use a simpler stop list for fact bank than the full stop list that you use in the Content component, so that it does not remove any useful terms from the code phrases.


Type:	String
Default:
Required:	No
Configuration Section:	Server or MySystem If you configure `StopList` in both the `[Server]` and system configuration sections, the system configuration overrides the server configuration for that system.
Example:	`StopList=English.dat`
See Also:	Language LanguageDirectory

SurfacePatternsFile

The path to the Passage Extractor surface patterns file. This parameter applies only when Type is set to PassageExtractor.

Passage Extractor uses surface patterns to find the possible forms that an answer to a particular question might take. It attempts to match candidate answers against the surface patterns to find the best match.

If you move or rename the surface patterns JSON file, set SurfacePatternsFile to the new name and location.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`SurfacePatternsFile=./passageextractor/configuration/surface_patterns_en.json`
See Also:

TermExpandCacheMaxRequests

When generating patterns to match the forms that an answer could take, Answer Server sends TermExpand actions to your Content component. In order to improve performance, Answer Server caches the results of these requests.

This parameter specifies the maximum number of requests to allow before the cache of term expansions is invalidated. If you set this parameter to zero then caching is disabled.


Type:	Integer
Default:	1000
Required:	No
Configuration Section:	MySystem
Example:	`TermExpandCacheMaxRequests=500`
See Also:	TermExpandCacheSize

TermExpandCacheSize

This parameter specifies the maximum number of term expansions to cache.


Type:	Integer
Default:	1000
Required:	No
Configuration Section:	MySystem
Example:	`TermExpandCacheSize=500`
See Also:	TermExpandCacheMaxRequests

TermExpandDefaults

When generating patterns to match the forms that an answer could take, Answer Server sends TermExpand actions to your Content component.

This parameter specifies the name of a section in the Answer Server configuration file that contains default values for action parameters, to send with each TermExpand action.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`TermExpandDefaults=TermExpandDefaultParams [TermExpandDefaultParams] MinDocOccs=5`
See Also:

My Vector Settings Configuration Parameters

This section describes the configuration parameters that you use to configure how the Passage Extractor system (systems where you set Type to PassageExtractor or PassageExtractorLLM) sends vector queries to the Content component to retrieve candidate answer documents.

####### EmbeddingsConfig

The name of a configuration section that contains settings for creating the embeddings that Answer Server uses to query. See My Embeddings Configuration Parameters.


Type:	String
Default:
Required:	Yes
Configuration Section:	MyVectorSettings
Example:	`EmbeddingsConfig=EmbeddingsModel`
See Also:

####### VectorField

The Content component fields that contain the vector values that you want to search. Separate multiple field names with commas. There must be no space before or after a comma.

The fields you list must be configured as VectorType in Content, and they must contain vector values that are compatible with the embeddings that you generate in Answer Server for queries (see EmbeddingsConfig).

When you specify multiple fields, Answer Server generates embeddings and then searches for matching vectors in any of the vector fields that you list.


Type:	String
Default:
Required:	Yes
Configuration Section:	MyVectorSettings
Example:	`VectorField=VECTORA`
See Also:	EmbeddingsConfig

####### My Embeddings Configuration Parameters

This section describes the configuration parameters that you use to configure a vector model to use to create embeddings to send in queries to the Content component for Passage Extractor systems (systems where you set Type to PassageExtractor and PassageExtractorLLM).

######## EmbeddingPrecision

The number of decimal places to use in the embedding values.

You can use a value between 1 and 10, to use that number of decimal places in the embedding values. If you set EmbeddingPrecision to be lower than 1, Knowledge Discovery uses the default value of 5. If you set it to a value higher than 10, it uses 10 decimal places.


Type:	Integer
Allowed Range:	Minimum: 1 Maximum: 10
Default:	5
Required:	No
Configuration Section:	MyEmbedding
Example:	`EmbeddingPrecision=6`
See Also:

######## ModelMaxSequenceLength

The maximum chunk size permitted by the embedding model. The chunk size is measured in tokens, which depends on the embedding model that you use.

This parameter has an effect only when Type is set to Transformer.


Type:	Integer
Default:	128
Required:	No
Configuration Section:	MyEmbedding
Example:	`ModelMaxSequenceLength=64`
See Also:	ModelMinimumFinalSequenceLength ModelSequenceOverlap

######## ModelName

The name of the model to use. This model name must match exactly the name of a model on Hugging Face.

When you start the server, Answer Server downloads the model from Hugging Face. It then caches it for future use. You can control the location of the cache by setting CacheDirectory.

You can optionally choose the version of the model to use, by setting ModelRevision.

This parameter has an effect only when Type is set to Transformer.


Type:	String
Default:
Required:	Yes, when you set Type to `Transformer`
Configuration Section:	MyEmbedding
Example:	`ModelName=google/flan-t5-small`
See Also:	Type CacheDirectory ModelRevision

######## Script

The path to a Lua script to use to generate the embeddings that passage extractor sends to the Content component to retrieve candidate documents. This parameter applies only when Type is set to Lua or Python.

For information about how to create the embedding generation script, see [Create an Embedding Generation Lua Script](../../../Manage Passage Extractor LLM/PassExt_CandidateRetrieval.htm#Create2) and [Create an Embedding Generation Python Script](../../../Manage Passage Extractor LLM/PassExt_CandidateRetrieval.htm#Create).


Type:	String
Default:
Required:	Yes, when Type is set to `Lua` or `Python`
Configuration Section:	MyEmbedding
Example:	`Script=answerserver/scripts/embeddings_script.lua`
See Also:

######## Type

The type of model that you want to use to generate the embeddings. You can use one of the following options:

Transformer. Use a sentence transformer model. For this type of model, you must also set ModelName.
Lua. Define a Lua script that you want to use. For this type of model, you must also set Script.
Python. Define a Python script that you want to use. For this type of model, you must also set Script.

The method you use must produce vectors that are compatible with the vectors you use in the Content component.


Type:	String
Default:
Required:	Yes
Configuration Section:	MyEmbedding
Example:	`Type=Transformer`
See Also:

Passage Extractor LLM System Configuration Parameters

This section describes the configuration parameters that you can use in Passage Extractor LLM systems (systems where you set Type to PassageExtractorLLM).

ACIMaxResults

The maximum number of results that Answer Server requests from the data Content component. This parameter applies only when Type is set to PassageExtractor, PassageExtractorLLM or RAG.


Type:	Integer
Default:	12
Required:	No
Configuration Section:	MySystem
Example:	`ACIMaxResults=15`
See Also:

AnswerCandidateEmbeddingsSettings

You must create the corresponding configuration section, and configure VectorField and EmbeddingsConfig. See My Vector Settings Configuration Parameters.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AnswerCandidateEmbeddingsSettings=VectorSettings [VectorSettings] EmbeddingsConfig=EmbeddingsSystem VectorField=VECTORA`
See Also:

CandidateRetrievalDefaults

For more information about the Content component Query action parameters, refer to the Content Component Help.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`CandidateRetrievalDefaults=CandidateRetrievalParams [CandidateRetrievalParams] DatabaseMatch=MyAnswersDB`
See Also:	AllowedQueryParameters

CandidateRetrievalOperator

The query operator to use between terms in passage extractor queries. This parameter applies only when Type is set to PassageExtractor, PassageExtractorLLM, or RAG.

In general, OpenText recommends that you use the default value.


Type:	String
Default:	space
Required:	No
Configuration Section:	MySystem
Example:	`CandidateRetrievalOperator=+`
See Also:	AllowedQueryParameters

ClassifierBehaviorFile

The location and name of the Passage Extractor classifier behavior file. This parameter applies only when Type is set to PassageExtractor or PassageExtractorLLM.

The primary classification is determined by a probability threshold, which is 0.85 by default.

If you move or rename the classification behavior JSON file, set ClassifierBehaviorFile to the new name and location.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`ClassifierBehaviorFile=./passageextractor/configuration/classifier_behavior.json`
See Also:	ClassifierFile LabelFile

ClassifierFile

The location and name of the Passage Extractor classifier file. This parameter applies only when Type is set to PassageExtractor or PassageExtractorLLM.

At startup, the question classifier uses the classifier file at this location, if it exists, or it saves the trained classifier resources to this location.


Type:	String
Default:
Required:	Yes, when Type is set to `PassageExtractor` or `PassageExtractorLLM`
Configuration Section:	MySystem
Example:	`ClassifierFile=./passageextractor/classifiertraining/svm_en.dat`
See Also:	LabelFile

IDOLACIPort

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.


Type:	Integer
Default:
Required:	Yes, when Type is set to `AnswerBank`, `PassageExtractor`, `PassageExtractorLLM`, or `RAG`
Configuration Section:	MySystem
Example:	`IDOLACIPort=6000`
See Also:	IDOLHost IDOLSSLConfig

IDOLGSSServiceName


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`IDOLGSSServiceName=CONTENT01`
See Also:	IDOLACIPort IDOLHost

IDOLHost

The host name or IP address of the Content component or Agentstore component that the system must connect to. You must also specify the component ACI port by using the IDOLACIPort parameter.

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.


Type:	String
Default:
Required:	Yes, when Type is set to `AnswerBank`, `PassageExtractor` or `PassageExtractorLLM`
Configuration Section:	MySystem
Example:	`IDOLHost=localhost`
See Also:	IDOLACIPort IDOLGSSServiceName IDOLSSLConfig

IDOLSSLConfig

This parameter configures the SSL connection to the component that you configure by using IDOLACIPort and IDOLHost.

NOTE: Answer Server uses the same SSL configuration for ACI and indexing requests to the Content or Agentstore.

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`IDOLSSLConfig=SSLOption2`
See Also:	IDOLACIPort IDOLHost Secure Socket Layer Parameters

LabelFile

The location and name of the Passage Extractor classifier label file. This parameter applies only when Type is set to PassageExtractor or PassageExtractorLLM.

At startup, the question classifier uses the label file at this location, if it exists, or it saves the trained classifier resources to this location.


Type:	String
Default:
Required:	Yes, when Type is set to `PassageExtractor` or `PassageExtractorLLM`
Configuration Section:	MySystem
Example:	`LabelFile=./passageextractor/classifiertraining/labels_en.dat`
See Also:	ClassifierFile

Language

The language to use for stemming. This parameter applies only to fact bank and passage extractor systems.

Answer Server uses stemming for fact bank and passage extractor to improve question parsing and answer matching.

Answer Server supports the same languages for stemming as the Content component. For more information, refer to Knowledge Discovery Expert.


Type:	String
Default:	English
Required:	No
Configuration Section:	Server or MySystem If you configure `Language` in both the `[Server]` and system configuration sections, the system configuration overrides the server configuration for that system.
Example:	`Language=French`
See Also:	LanguageDirectory StopList

MinScore

The minimum score that an answer from this system must have to return as a result for the Ask action.


Type:	Number
Default:	0
Allowed Range:	Minimum: 0 Maximum: 100
Required:	No
Configuration Section:	MySystem
Example:	`MinScore=60`
See Also:	Ask action MinScore action parameter

ModuleID

The name of a configuration file section that contains the information for a Large Language Model (LLM) that you want to use to extract answers. This parameter applies only when Type is set to PassageExtractorLLM or RAG.

You must create and configure the associated configuration section. See LLM Module Configuration Parameters.


Type:	String
Default:
Required:	Yes, when Type is set to `PassageExtractorLLM` or `RAG`
Configuration Section:	MySystem
Example:	`ModuleID=LLMExtractiveQuestionAnswering-Small`
See Also:	LLM Module Configuration Parameters

LLM Module Configuration Parameters

This section describes the configuration parameters that you use to configure a Large Language Model (LLM) to use for your Passage Extractor LLM systems (systems where you set Type to PassageExtractorLLM).

####### AccessToken

An access token for Hugging Face to use to access a private model. This option allows you to use private models that you have access to.

This parameter has an effect only when Type is set to ExtractiveQuestionAnsweringLLM or GenerativeLLM.


Type:	String
Default:
Required:	No
Configuration Section:	MyLLMModule
Example:	`AccessToken=hf_abcDEFghiJKLmnoPQRstuVWXyzaBCdefGH`
See Also:	ModelName ModelRevision

####### CacheDirectory

The location that Knowledge Discovery uses to download and store the models that it downloads from Hugging Face.

This parameter has an effect only when Type is set to ExtractiveQuestionAnsweringLLM or GenerativeLLM.


Type:	String
Default:	`~/.cache/huggingface/hub`
Required:	No
Configuration Section:	MyLLMModule
Example:	`CacheDirectory=C:\LLMs\HuggingFace\AnswerServer`
See Also:	Type

####### ChunkSize

The maximum number of tokens of the full tokenized question and context that is provided to the generative model. If the total number of tokens is larger, Knowledge Discovery sends the input context in multiple chunks and combines the results from each chunk.

This parameter has an effect only when Type is set to GenerativeLLM.


Type:	String
Default:	512
Required:	No
Configuration Section:	MyLLMModule
Example:	`ChunkSize=120`
See Also:	Type

####### Device

The type of processor to use to process question answering models. You can use one of the following values:

CPU
CUDA

To use the CUDA option, you must have a compatible GPU available for use, or Knowledge Discovery fails with an error. It does not default to using the CPU if there is no compatible GPU available.

This parameter has an effect only when Type is set to ExtractiveQuestionAnsweringLLM or GenerativeLLM.


Type:	String
Default:	CPU
Required:	No
Configuration Section:	MyLLMModule
Example:	`Device=cuda`
See Also:	ModelName Type

####### GreedySearch

Set GreedySearch to False to use an alternative algorithm for generating text.

By default, the generative model uses a greedy search algorithm to determine the output tokens. In this approach, the model chooses the token with the highest probability as the next output token.

You can set GreedySearch to False to use a multinomial sampling algorithm instead, which chooses the next token randomly based on a probability distribution over the entire vocabulary of the model. This option can sometimes give better results for longer sequences. However, the results vary for a particular input because the algorithm contains an element of randomness.

This parameter has an effect only when Type is set to GenerativeLLM.


Type:	Boolean
Default:	True
Required:	No
Configuration Section:	MyLLMModule
Example:	`GreedySerach=False`
See Also:	Type

####### ModelName

The name of the model to use. This model name must match exactly the name of a model on Hugging Face.

When you start the server, Answer Server downloads the model from Hugging Face. It then caches it for future use. You can control the location of the cache by setting CacheDirectory.

You can optionally choose the version of the model to use, by setting ModelRevision.

This parameter has an effect only when Type is set to ExtractiveQuestionAnsweringLLM or GenerativeLLM.


Type:	String
Default:
Required:	Yes, when Type is set to `ExtractiveQuestionAnsweringLLM` or `GenerativeLLM`
Configuration Section:	MyLLMModule
Example:	`ModelName=google/flan-t5-small`
See Also:	Type CacheDirectory ModelRevision

####### ModelRevision

The revision of the model to use (you specify the model in ModelName).

By default, Answer Server downloads and uses the main revision of the model that you specify. To use a different revision, set ModelRevision to a branch name, tag name, or commit ID for the model. You can view the commit history of a model on the model page on Hugging Face.

This parameter has an effect only when Type is set to ExtractiveQuestionAnsweringLLM or GenerativeLLM.


Type:	String
Default:	main
Required:	No
Configuration Section:	MyLLMModule
Example:	`ModelRevision=version-7.2`
See Also:	Type ModelName

####### NumProcessors

The number of processors to use to run the LLM generation.

This parameter has an effect only when Type is set to GenerativeLLM or ExtractiveQuestionAnsweringLLM.

IMPORTANT: The value for NumProcessors applies to all your GenerativeLLM, ExtractiveQuestionAnsweringLLM, and Transformer models (see My Embeddings Configuration Parameters). If you set this parameter in multiple sections, Answer Server uses the last value.


Type:	Integer
Default:	the LLM uses all available processors
Required:	No
Configuration Section:	MyLLMModule
Example:	`NumProcessors=1`
See Also:	Type

####### OfflineMode

Set OfflineMode to True to use only a locally cached version of the configured model (and never download an updated version from Hugging Face). In this case, you must have the required models cached in the appropriate place.

NOTE: If Answer Server cannot connect to the internet, it looks for the model in the local cache directory even if you have set OfflineMode to False.

This parameter has an effect only when Type is set to ExtractiveQuestionAnsweringLLM or GenerativeLLM.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	MyLLMModule
Example:	`OfflineMode=True`
See Also:	ModelName

####### RequirementsFile

The path to the requirements.txt file that specifies any third-party Python modules that are required by the script that you configure in Script. Knowledge Discovery installs these requirements by using pip.

This parameter has an effect only when Type is set to GenerativePython.


Type:	String
Default:
Required:	No
Configuration Section:	MyLLMModule
Example:	`RequirementsFile=answerserver/scripts/requirements.txt`
See Also:

####### Script

The path to a Lua or Python script to use for extractive or generative question answering. This parameter applies only when Type is set to ExtractiveQuestionAnsweringLua, GenerativeLua or GenerativePython.

For information about how to create the question answering script, see [Create a Question Answering Lua Script](../../../Manage Passage Extractor LLM/PassExtLLM_Configure.htm#Create2) and [Create a Question Answering Python Script](../../../Manage Passage Extractor LLM/PassExtLLM_Configure.htm#Create3).


Type:	String
Default:
Required:	Yes, when Type is set to `ExtractiveQuestionAnsweringLua`, `GenerativeLua`, or `GenerativePython`
Configuration Section:	MyLLMModule
Example:	`Script=answerserver/scripts/extractive_script.lua`
See Also:

####### Type

The type of model to use for your passage extractor LLM or RAG system.

For a RAG system, you can use the following options:

GenerativeLua. Use a Lua script that performs generative question answering. For this type, you must set Script to the name and path for the script to use.
GenerativePython. Use a Python script that performs generative question answering. For this type, you must set Script to the name and path for the script to use.

For a passage extractor LLM system, you can use GenerativeLua and GenerativePython, or one of the following options:

ExtractiveQuestionAnsweringLLM. Use an extractive question answering LLM from Hugging Face. For this type, you must set ModelName to the model to use.
GenerativeLLM. Use an generative LLM from Hugging Face. For this type, you must set ModelName to set the model to use.
ExtractiveQuestionAnsweringLua. Use a Lua script that performs extractive question answering. For this type, you must set Script to the name and path for the script to use.


Type:	String
Default:
Required:	Yes
Configuration Section:	MyLLMModule
Example:	`Type=GenerativeLLM`
See Also:	ModelName Script

My Vector Settings Configuration Parameters

####### EmbeddingsConfig

The name of a configuration section that contains settings for creating the embeddings that Answer Server uses to query. See My Embeddings Configuration Parameters.


Type:	String
Default:
Required:	Yes
Configuration Section:	MyVectorSettings
Example:	`EmbeddingsConfig=EmbeddingsModel`
See Also:

####### VectorField

The Content component fields that contain the vector values that you want to search. Separate multiple field names with commas. There must be no space before or after a comma.

When you specify multiple fields, Answer Server generates embeddings and then searches for matching vectors in any of the vector fields that you list.


Type:	String
Default:
Required:	Yes
Configuration Section:	MyVectorSettings
Example:	`VectorField=VECTORA`
See Also:	EmbeddingsConfig

####### My Embeddings Configuration Parameters

######## AccessToken

An access token for Hugging Face to use to access a private model. This option allows you to use private models that you have access to.

This parameter has an effect only when Type is set to Transformer.


Type:	String
Default:
Required:	No
Configuration Section:	MyEmbedding
Example:	`AccessToken=hf_abcDEFghiJKLmnoPQRstuVWXyzaBCdefGH`
See Also:	ModelName ModelRevision

######## CacheDirectory

The location that Knowledge Discovery uses to download and store the models that it downloads from Hugging Face.

This parameter has an effect only when Type is set to Transformer.


Type:	String
Default:	`~/.cache/huggingface/hub`
Required:	No
Configuration Section:	MyEmbedding
Example:	`CacheDirectory=C:\LLMs\HuggingFace\AnswerServer`
See Also:	Type

######## DataLimit

The maximum start offset (in bytes) of text used to generate any embedding input. You can use this option to limit the amount of processing Answer Server performs if it receives a large file.

When Answer Server generates embeddings, it can use a chunk of text that ends after this limit, but not a chunk of text that starts after this limit. For example, if you set DataLimit to 3000, then you might get an embedding with start and end offsets [2300, 3100], but not an embedding with start offset 3050.

DataLimit must be either a positive integer, or -1 to specify no limit.

This parameter has an effect only when Type is set to Transformer.


Type:	Integer
Default:	-1 (no limit)
Required:	No
Configuration Section:	MyEmbedding
Example:	`DataLimit=1000`
See Also:

######## Device

The type of processor to use to process embedding models. You can use one of the following values:

CPU
CUDA

To use the CUDA option, you must have a compatible GPU available for use, or Knowledge Discovery fails with an error. It does not default to using the CPU if there is no compatible GPU available.

This parameter has an effect only when Type is set to Transformer.


Type:	String
Default:	CPU
Required:	No
Configuration Section:	MyEmbedding
Example:	`Device=cuda`
See Also:	Type

######## EmbeddingPrecision

The number of decimal places to use in the embedding values.


Type:	Integer
Allowed Range:	Minimum: 1 Maximum: 10
Default:	5
Required:	No
Configuration Section:	MyEmbedding
Example:	`EmbeddingPrecision=6`
See Also:

######## ModelMaxSequenceLength

The maximum chunk size permitted by the embedding model. The chunk size is measured in tokens, which depends on the embedding model that you use.

This parameter has an effect only when Type is set to Transformer.


Type:	Integer
Default:	128
Required:	No
Configuration Section:	MyEmbedding
Example:	`ModelMaxSequenceLength=64`
See Also:	ModelMinimumFinalSequenceLength ModelSequenceOverlap

######## ModelMinimumFinalSequenceLength

The minimum length (in tokens) of the final chunk of text used to generate embeddings.

When the input text is longer than the maximum chunk size for your model (see ModelMaxSequenceLength), Knowledge Discovery splits the text into chunks and generates multiple embeddings. Use ModelMinimumFinalSequenceLength to specify the minimum length of text to use to generate the final embedding for your input text.

This value must be non-negative and no greater than the value for ModelMaxSequenceLength.

This parameter has an effect only when Type is set to Transformer.


Type:	Integer
Default:	Half the value of ModelMaxSequenceLength (rounded down) plus one
Required:	No
Configuration Section:	MyEmbedding
Example:	`ModelMinimumFinalSequenceLength=70`
See Also:	ModelMaxSequenceLength ModelSequenceOverlap

######## ModelName

The name of the model to use. This model name must match exactly the name of a model on Hugging Face.

When you start the server, Answer Server downloads the model from Hugging Face. It then caches it for future use. You can control the location of the cache by setting CacheDirectory.

You can optionally choose the version of the model to use, by setting ModelRevision.

This parameter has an effect only when Type is set to Transformer.


Type:	String
Default:
Required:	Yes, when you set Type to `Transformer`
Configuration Section:	MyEmbedding
Example:	`ModelName=google/flan-t5-small`
See Also:	Type CacheDirectory ModelRevision

######## ModelRevision

The revision of the model to use (you specify the model in ModelName).

This parameter has an effect only when Type is set to Transformer.


Type:	String
Default:	main
Required:	No
Configuration Section:	MyEmbedding
Example:	`ModelRevision=version-7.2`
See Also:	Type ModelName

######## ModelSequenceOverlap

The length (in tokens) that text used to generate successive embeddings must overlap by.

When the input text is longer than the maximum chunk size for your model (see ModelMaxSequenceLength), Knowledge Discovery splits the text into chunks and generates multiple embeddings. Use ModelSequenceOverlap to specify an overlap to use to generate these embeddings.

This value must be non-negative and less than the value for ModelMaxSequenceLength.

This parameter has an effect only when Type is set to Transformer.


Type:	Integer
Default:	0
Required:	No
Configuration Section:	MyEmbedding
Example:	`ModelSequenceOverlap=40`
See Also:	ModelMaxSequenceLength ModelMinimumFinalSequenceLength

######## NumProcessors

The number of processors to use to run the LLM generation.

This parameter has an effect only when Type is set to Transformer.

IMPORTANT: The value for NumProcessors applies to all your Transformer, GenerativeLLM, and ExtractiveQuestionAnsweringLLMmodels (see LLM Module Configuration Parameters). If you set this parameter in multiple sections, Answer Server uses the last value.


Type:	Integer
Default:	the LLM uses all available processors
Required:	No
Configuration Section:	MyEmbedding
Example:	`NumProcessors=1`
See Also:	Type

######## OfflineMode

NOTE: If Answer Server cannot connect to the internet, it looks for the model in the local cache directory even if you have set OfflineMode to False.

This parameter has an effect only when Type is set to Transformer.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	MyEmbedding
Example:	`OfflineMode=True`
See Also:	ModelName

######## RequirementsFile

This parameter has an effect only when Type is set to Python.


Type:	String
Default:
Required:	No
Configuration Section:	MyEmbedding
Example:	`RequirementsFile=answerserver/scripts/requirements.txt`
See Also:

######## Script


Type:	String
Default:
Required:	Yes, when Type is set to `Lua` or `Python`
Configuration Section:	MyEmbedding
Example:	`Script=answerserver/scripts/embeddings_script.lua`
See Also:

######## Type

The type of model that you want to use to generate the embeddings. You can use one of the following options:

Transformer. Use a sentence transformer model. For this type of model, you must also set ModelName.
Lua. Define a Lua script that you want to use. For this type of model, you must also set Script.
Python. Define a Python script that you want to use. For this type of model, you must also set Script.

The method you use must produce vectors that are compatible with the vectors you use in the Content component.


Type:	String
Default:
Required:	Yes
Configuration Section:	MyEmbedding
Example:	`Type=Transformer`
See Also:

RAG System Configuration Parameters

This section describes the configuration parameters that you can use in Retrieval-Augmented Generation systems (systems where you set Type to RAG).

ACIMaxResults

The maximum number of results that Answer Server requests from the data Content component. This parameter applies only when Type is set to PassageExtractor, PassageExtractorLLM or RAG.


Type:	Integer
Default:	12
Required:	No
Configuration Section:	MySystem
Example:	`ACIMaxResults=15`
See Also:

AnswerCandidateEmbeddingsSettings

You must create the corresponding configuration section, and configure VectorField and EmbeddingsConfig. See My Vector Settings Configuration Parameters.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AnswerCandidateEmbeddingsSettings=VectorSettings [VectorSettings] EmbeddingsConfig=EmbeddingsSystem VectorField=VECTORA`
See Also:

AssistantRole

The value that Answer Server uses in the conversation history session_data for lines that represent the generated responses. This parameter applies only when Type is set to RAG.

By default, when you access session data in your RAG script, Answer Server returns the conversation history with the user input tagged as User and the generated responses marked as Assistant. To use a different value for the generated responses, set AssistantRole to the name to use.

Answer Server uses these values in the call to the LLM with the topic template, when you set TopicTemplatePath. It does not use them in the final question answering call to the LLM.


Type:	String
Default:	Assistant
Required:	No
Configuration Section:	MySystem
Example:	`AssistantRole=ChatBot`
See Also:	UserRole

CandidateRetrievalDefaults

For more information about the Content component Query action parameters, refer to the Content Component Help.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`CandidateRetrievalDefaults=CandidateRetrievalParams [CandidateRetrievalParams] DatabaseMatch=MyAnswersDB`
See Also:	AllowedQueryParameters

CandidateRetrievalOperator

The query operator to use between terms in passage extractor queries. This parameter applies only when Type is set to PassageExtractor, PassageExtractorLLM, or RAG.

In general, OpenText recommends that you use the default value.


Type:	String
Default:	space
Required:	No
Configuration Section:	MySystem
Example:	`CandidateRetrievalOperator=+`
See Also:	AllowedQueryParameters

ContextJSONFields

A set of fields to use to add structure and metadata to the prompt context that Answer Server sends to the LLM.

By default, Answer Server constructs a prompt to send to the LLM by using the following basic format:

DOCUMENT: <doc_source>
<doc_content>

You can set ContextJSONFields to a list of fields that you want to include in the prompt, and Answer Server generates a JSON object with these fields and the corresponding values. This option can improve the ability of the LLM to differentiate between document summaries and parse the information.

You must include the text field, and you can include the following optional fields:

source
title
database
relevance

Answer Server writes the fields in the prompt context JSON in the order that the occur in the configuration parameter. You cannot specify a field more than once.

NOTE: The last document returned might have malformed JSON if the prompt context has to be truncated due to token limits.


Type:	String
Default:	uses a basic format for the prompt: `DOCUMENT: <doc_source> <doc_content>`
Required:	No
Configuration Section:	MySystem
Example:	`CustomJSONFields=Source,Text,Database,Relevance` This example results in the following prompt context JSON: `{ "source": <doc_source>, "text": <doc_content>, "database": <doc_database>, "relevance": <doc_relevance> }`
See Also:	My Vector Settings Configuration Parameters

IDOLACIPort

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.


Type:	Integer
Default:
Required:	Yes, when Type is set to `AnswerBank`, `PassageExtractor`, `PassageExtractorLLM`, or `RAG`
Configuration Section:	MySystem
Example:	`IDOLACIPort=6000`
See Also:	IDOLHost IDOLSSLConfig

IDOLGSSServiceName


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`IDOLGSSServiceName=CONTENT01`
See Also:	IDOLACIPort IDOLHost

IDOLHost

The host name or IP address of the Content component or Agentstore component that the system must connect to. You must also specify the component ACI port by using the IDOLACIPort parameter.

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.


Type:	String
Default:
Required:	Yes, when Type is set to `AnswerBank`, `PassageExtractor` or `PassageExtractorLLM`
Configuration Section:	MySystem
Example:	`IDOLHost=localhost`
See Also:	IDOLACIPort IDOLGSSServiceName IDOLSSLConfig

IDOLSSLConfig

This parameter configures the SSL connection to the component that you configure by using IDOLACIPort and IDOLHost.

NOTE: Answer Server uses the same SSL configuration for ACI and indexing requests to the Content or Agentstore.

For a system where Type is set to AnswerBank, this parameter points to the Agentstore component that stores questions and question equivalence classes.

For a system where Type is set to PassageExtractor, PassageExtractorLLM, or RAG, this parameter points to the Content component that contains the data that you want to use to find answers.

This parameter is not required for systems where Type is set to FactBank.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`IDOLSSLConfig=SSLOption2`
See Also:	IDOLACIPort IDOLHost Secure Socket Layer Parameters

MaxQuestionSize

The maximum number of tokens that the question to Answer Server can contain. If a user question contains more than this number of tokens, Answer Server rejects the question and returns an error.

The token count for a question depends on the model that you use. To obtain an accurate token count for your model, you must provide a get_token_count function in the script that you use to call the LLM. See [Create a RAG Script](../../../Manage RAG Systems/RAG_Configure.htm#Create).


Type:	Integer
Default:	50
Required:	No
Configuration Section:	MySystem
Example:	`MaxQuestionSize=70`
See Also:

MinScore

The minimum score that an answer from this system must have to return as a result for the Ask action.


Type:	Number
Default:	0
Allowed Range:	Minimum: 0 Maximum: 100
Required:	No
Configuration Section:	MySystem
Example:	`MinScore=60`
See Also:	Ask action MinScore action parameter

ModuleID

You must create and configure the associated configuration section. See LLM Module Configuration Parameters.


Type:	String
Default:
Required:	Yes, when Type is set to `PassageExtractorLLM` or `RAG`
Configuration Section:	MySystem
Example:	`ModuleID=LLMExtractiveQuestionAnswering-Small`
See Also:	LLM Module Configuration Parameters

PromptTemplatePath

The path to the RAG prompt template file. This parameter applies only when Type is set to RAG.

The RAG system sends a prompt to send to the LLM with the original user question and the context documents from your Knowledge Discovery index. The prompt template is a text file that defines the format of this prompt. In the template, you must use the token {{question}}, which Answer Server replaces with the user question, and the token {{context}}, which Answer Server replaces with relevant text from the candidate documents.

For example:

Provide an answer for {{question}} based on the following text: {{context}}

For each question that you ask the RAG system, Answer Server substitutes the question and context documents, and sends the result to the configured LLM to generate an answer.

CAUTION: Answer Server substitutes user-supplied input, in the form of the question text, into the template before it passes the resulting text to the LLM.

You must design your prompt templates to mitigate against prompt engineering attacks, where malicious users create input that changes the LLM behavior. The best practice varies according to the model that you use, so you must consult the recommendations for your chosen model.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`PromptTemplatePath=./rag/prompts/rag_prompt.txt`
See Also:

PromptTokenLimit

The maximum number of tokens to include in the prompt that Answer Server supplies to the configured LLM. Answer Server keeps to this limit by truncating the context documents that it includes in the prompt.

This limit might be important in some cases, for example when you use a model that charges according to the size of the prompt that you provide. Answer Server enforces the maximum prompt size so that the prompt and context never exceeds the limit.

The token count for a prompt depends on the model that you use. To obtain an accurate token count for your model, you must provide a get_token_count function in the script that you use to call the LLM. See Configure the RAG System.

NOTE: Answer Server applies the token limit to the whole Ask action, even if this includes multiple calls to the LLM. For example, when you set TopicTemplatePath to use a topic template to generate topics, Answer Server counts the tokens sent for the topic generation call in the prompt token limit, as well as the final prompt.


Type:	Integer
Default:
Required:	No
Configuration Section:	MySystem
Example:	`MaxPromptSize=500`
See Also:

ReferenceField

The field to use as the source that Answer Server reports for documents that it uses as context.

By default, when Answer Server returns context documents from the Content component, it uses the autn:reference. Set ReferenceField to use a different reference field from Content as the identifier for a context document.

NOTE: If you specify a reference field that does not exist for a particular context document, Answer Server uses the autn:reference.


Type:	String
Default:	autn:reference
Required:	No
Configuration Section:	MySystem
Example:	`ReferenceField=MyVectorReference`
See Also:

RetrievalType

The method to use to construct query text when Answer Server retrieves candidate documents from the Content component.

You can use one of the following options:

conceptual send a conceptual search to the Content component
vector generate embeddings for the user and send a vector query to the Content component
mixed use a combination of a conceptual and vector search.


Type:	String
Default:	mixed, if there is an embedding system configured. Otherwise, conceptual.
Required:	No
Configuration Section:	MySystem
Example:	`RetrievalType=vector`
See Also:	My Vector Settings Configuration Parameters

TopicLandmark

The value that Answer Server can use to extract the topics from the results of a topic template query. This parameter applies only when Type is set to RAG.

When you set TopicTemplatePath, Answer Server sends an additional template to the configured LLM to generate topics from the conversation history, which Answer Server can use in the query to the Content component to return more relevant candidate documents. By default, Answer Server finds the landmark Topics in the LLM result to extract these topics. Set TopicLandmark if you want to use a different value.


Type:	String
Default:	Topics
Required:	No
Configuration Section:	MySystem
Example:	`TopicLandmark=ConversationTopics`
See Also:

TopicTemplatePath

The path to the topic template file. This parameter applies only when Type is set to RAG.

The topic template allows you to use the answer LLM to generate additional context to send in the query to the Content component. The template must include the token {{history}}, which Answer Server replaces with the conversation history. The LLM uses this topic prompt and conversation history to return the topics in the conversation. Answer Server uses these topics in the query to Content, which might help provide more relevant candidate document summaries to use for the RAG query.

You must design your topic prompt template so that it generates answers that contain a landmark string, for example Topics, immediately followed by an array of strings. You can configure the landmark that Answer Server looks for by setting TopicLandmark. Answer Server then parses the strings to use as topics in its candidate generation query. It ignores any text before the landmark, so you can optionally use it for generated explanations for the answers (chain of thought prompting).

If the content that follows the landmark is not a valid array, Answer Server does not add any contextual topics for the query.

When you create your topic template, you must consider any PromptTokenLimit that you set for your RAG system. Answer Server applies the prompt token limit to all tokens it sends to the LLM as part of a single Ask action, so the size of your template also affects the amount of candidate document summaries that Answer Server sends to the LLM to generate the final response.

For example:

A snippet of a conversation will be shown below after >>>>>Input:<<<<<. 
Read the conversation carefully and decide the current topic of the conversation. In 
particular, you should decide what words like "it", "they", "he" or "she" might be 
referring to. Be aware that topics can change during a conversation, and if it has 
changed then you should choose the topic that is related to the most recent question 
that the user sent.

Use the following format for the output, listing the topics in an array:

Explanation: <Your explanation>
Topics: ["<First topic>", "<Second topic>"]

Do not attempt to continue the conversation yourself.
Please keep your answer as brief as possible.

>>>>>Input:<<<<<
{{history}}
Output:

CAUTION: Answer Server substitutes user-supplied input, in the form of the question text, into the template before it passes the resulting text to the LLM.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`TopicTemplatePath=./rag/prompts/rag_topics.txt`
See Also:

UserRole

The value that Answer Server uses in the conversation history session_data for lines that represent the user questions. This parameter applies only when Type is set to RAG.

By default, when you access session data in your RAG script, Answer Server returns the conversation history with the user input tagged as User and the automated responses marked as Assistant. To use a different value for the user name, set UserRole to the name to use.

Answer Server uses these values in the call to the LLM with the topic template, when you set TopicTemplatePath. It does not use them in the final question answering call to the LLM.


Type:	String
Default:	User
Required:	No
Configuration Section:	MySystem
Example:	`UserRole=Customer`
See Also:	AssistantRole

LLM Module Configuration Parameters

####### AccessToken

An access token for Hugging Face to use to access a private model. This option allows you to use private models that you have access to.

This parameter has an effect only when Type is set to ExtractiveQuestionAnsweringLLM or GenerativeLLM.


Type:	String
Default:
Required:	No
Configuration Section:	MyLLMModule
Example:	`AccessToken=hf_abcDEFghiJKLmnoPQRstuVWXyzaBCdefGH`
See Also:	ModelName ModelRevision

####### CacheDirectory

The location that Knowledge Discovery uses to download and store the models that it downloads from Hugging Face.

This parameter has an effect only when Type is set to ExtractiveQuestionAnsweringLLM or GenerativeLLM.


Type:	String
Default:	`~/.cache/huggingface/hub`
Required:	No
Configuration Section:	MyLLMModule
Example:	`CacheDirectory=C:\LLMs\HuggingFace\AnswerServer`
See Also:	Type

####### ChunkSize

This parameter has an effect only when Type is set to GenerativeLLM.


Type:	String
Default:	512
Required:	No
Configuration Section:	MyLLMModule
Example:	`ChunkSize=120`
See Also:	Type

####### Device

The type of processor to use to process question answering models. You can use one of the following values:

CPU
CUDA

To use the CUDA option, you must have a compatible GPU available for use, or Knowledge Discovery fails with an error. It does not default to using the CPU if there is no compatible GPU available.

This parameter has an effect only when Type is set to ExtractiveQuestionAnsweringLLM or GenerativeLLM.


Type:	String
Default:	CPU
Required:	No
Configuration Section:	MyLLMModule
Example:	`Device=cuda`
See Also:	ModelName Type

####### GreedySearch

Set GreedySearch to False to use an alternative algorithm for generating text.

By default, the generative model uses a greedy search algorithm to determine the output tokens. In this approach, the model chooses the token with the highest probability as the next output token.

This parameter has an effect only when Type is set to GenerativeLLM.


Type:	Boolean
Default:	True
Required:	No
Configuration Section:	MyLLMModule
Example:	`GreedySerach=False`
See Also:	Type

####### ModelName

The name of the model to use. This model name must match exactly the name of a model on Hugging Face.

When you start the server, Answer Server downloads the model from Hugging Face. It then caches it for future use. You can control the location of the cache by setting CacheDirectory.

You can optionally choose the version of the model to use, by setting ModelRevision.

This parameter has an effect only when Type is set to ExtractiveQuestionAnsweringLLM or GenerativeLLM.


Type:	String
Default:
Required:	Yes, when Type is set to `ExtractiveQuestionAnsweringLLM` or `GenerativeLLM`
Configuration Section:	MyLLMModule
Example:	`ModelName=google/flan-t5-small`
See Also:	Type CacheDirectory ModelRevision

####### ModelRevision

The revision of the model to use (you specify the model in ModelName).

This parameter has an effect only when Type is set to ExtractiveQuestionAnsweringLLM or GenerativeLLM.


Type:	String
Default:	main
Required:	No
Configuration Section:	MyLLMModule
Example:	`ModelRevision=version-7.2`
See Also:	Type ModelName

####### OfflineMode

NOTE: If Answer Server cannot connect to the internet, it looks for the model in the local cache directory even if you have set OfflineMode to False.

This parameter has an effect only when Type is set to ExtractiveQuestionAnsweringLLM or GenerativeLLM.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	MyLLMModule
Example:	`OfflineMode=True`
See Also:	ModelName

####### RequirementsFile

This parameter has an effect only when Type is set to GenerativePython.


Type:	String
Default:
Required:	No
Configuration Section:	MyLLMModule
Example:	`RequirementsFile=answerserver/scripts/requirements.txt`
See Also:

####### Script


Type:	String
Default:
Required:	Yes, when Type is set to `ExtractiveQuestionAnsweringLua`, `GenerativeLua`, or `GenerativePython`
Configuration Section:	MyLLMModule
Example:	`Script=answerserver/scripts/extractive_script.lua`
See Also:

####### Type

The type of model to use for your passage extractor LLM or RAG system.

For a RAG system, you can use the following options:

GenerativeLua. Use a Lua script that performs generative question answering. For this type, you must set Script to the name and path for the script to use.
GenerativePython. Use a Python script that performs generative question answering. For this type, you must set Script to the name and path for the script to use.

For a passage extractor LLM system, you can use GenerativeLua and GenerativePython, or one of the following options:

ExtractiveQuestionAnsweringLLM. Use an extractive question answering LLM from Hugging Face. For this type, you must set ModelName to the model to use.
GenerativeLLM. Use an generative LLM from Hugging Face. For this type, you must set ModelName to set the model to use.
ExtractiveQuestionAnsweringLua. Use a Lua script that performs extractive question answering. For this type, you must set Script to the name and path for the script to use.


Type:	String
Default:
Required:	Yes
Configuration Section:	MyLLMModule
Example:	`Type=GenerativeLLM`
See Also:	ModelName Script

My Vector Settings Configuration Parameters

####### EmbeddingsConfig

The name of a configuration section that contains settings for creating the embeddings that Answer Server uses to query. See My Embeddings Configuration Parameters.


Type:	String
Default:
Required:	Yes
Configuration Section:	MyVectorSettings
Example:	`EmbeddingsConfig=EmbeddingsModel`
See Also:

####### VectorField

The Content component fields that contain the vector values that you want to search. Separate multiple field names with commas. There must be no space before or after a comma.

When you specify multiple fields, Answer Server generates embeddings and then searches for matching vectors in any of the vector fields that you list.


Type:	String
Default:
Required:	Yes
Configuration Section:	MyVectorSettings
Example:	`VectorField=VECTORA`
See Also:	EmbeddingsConfig

####### My Embeddings Configuration Parameters

######## AccessToken

An access token for Hugging Face to use to access a private model. This option allows you to use private models that you have access to.

This parameter has an effect only when Type is set to Transformer.


Type:	String
Default:
Required:	No
Configuration Section:	MyEmbedding
Example:	`AccessToken=hf_abcDEFghiJKLmnoPQRstuVWXyzaBCdefGH`
See Also:	ModelName ModelRevision

######## CacheDirectory

The location that Knowledge Discovery uses to download and store the models that it downloads from Hugging Face.

This parameter has an effect only when Type is set to Transformer.


Type:	String
Default:	`~/.cache/huggingface/hub`
Required:	No
Configuration Section:	MyEmbedding
Example:	`CacheDirectory=C:\LLMs\HuggingFace\AnswerServer`
See Also:	Type

######## DataLimit

The maximum start offset (in bytes) of text used to generate any embedding input. You can use this option to limit the amount of processing Answer Server performs if it receives a large file.

DataLimit must be either a positive integer, or -1 to specify no limit.

This parameter has an effect only when Type is set to Transformer.


Type:	Integer
Default:	-1 (no limit)
Required:	No
Configuration Section:	MyEmbedding
Example:	`DataLimit=1000`
See Also:

######## Device

The type of processor to use to process embedding models. You can use one of the following values:

CPU
CUDA

To use the CUDA option, you must have a compatible GPU available for use, or Knowledge Discovery fails with an error. It does not default to using the CPU if there is no compatible GPU available.

This parameter has an effect only when Type is set to Transformer.


Type:	String
Default:	CPU
Required:	No
Configuration Section:	MyEmbedding
Example:	`Device=cuda`
See Also:	Type

######## EmbeddingPrecision

The number of decimal places to use in the embedding values.


Type:	Integer
Allowed Range:	Minimum: 1 Maximum: 10
Default:	5
Required:	No
Configuration Section:	MyEmbedding
Example:	`EmbeddingPrecision=6`
See Also:

######## ModelMaxSequenceLength

The maximum chunk size permitted by the embedding model. The chunk size is measured in tokens, which depends on the embedding model that you use.

This parameter has an effect only when Type is set to Transformer.


Type:	Integer
Default:	128
Required:	No
Configuration Section:	MyEmbedding
Example:	`ModelMaxSequenceLength=64`
See Also:	ModelMinimumFinalSequenceLength ModelSequenceOverlap

######## ModelMinimumFinalSequenceLength

The minimum length (in tokens) of the final chunk of text used to generate embeddings.

This value must be non-negative and no greater than the value for ModelMaxSequenceLength.

This parameter has an effect only when Type is set to Transformer.


Type:	Integer
Default:	Half the value of ModelMaxSequenceLength (rounded down) plus one
Required:	No
Configuration Section:	MyEmbedding
Example:	`ModelMinimumFinalSequenceLength=70`
See Also:	ModelMaxSequenceLength ModelSequenceOverlap

######## ModelName

The name of the model to use. This model name must match exactly the name of a model on Hugging Face.

When you start the server, Answer Server downloads the model from Hugging Face. It then caches it for future use. You can control the location of the cache by setting CacheDirectory.

You can optionally choose the version of the model to use, by setting ModelRevision.

This parameter has an effect only when Type is set to Transformer.


Type:	String
Default:
Required:	Yes, when you set Type to `Transformer`
Configuration Section:	MyEmbedding
Example:	`ModelName=google/flan-t5-small`
See Also:	Type CacheDirectory ModelRevision

######## ModelRevision

The revision of the model to use (you specify the model in ModelName).

This parameter has an effect only when Type is set to Transformer.


Type:	String
Default:	main
Required:	No
Configuration Section:	MyEmbedding
Example:	`ModelRevision=version-7.2`
See Also:	Type ModelName

######## ModelSequenceOverlap

The length (in tokens) that text used to generate successive embeddings must overlap by.

When the input text is longer than the maximum chunk size for your model (see ModelMaxSequenceLength), Knowledge Discovery splits the text into chunks and generates multiple embeddings. Use ModelSequenceOverlap to specify an overlap to use to generate these embeddings.

This value must be non-negative and less than the value for ModelMaxSequenceLength.

This parameter has an effect only when Type is set to Transformer.


Type:	Integer
Default:	0
Required:	No
Configuration Section:	MyEmbedding
Example:	`ModelSequenceOverlap=40`
See Also:	ModelMaxSequenceLength ModelMinimumFinalSequenceLength

######## OfflineMode

NOTE: If Answer Server cannot connect to the internet, it looks for the model in the local cache directory even if you have set OfflineMode to False.

This parameter has an effect only when Type is set to Transformer.


Type:	Boolean
Default:	False
Required:	No
Configuration Section:	MyEmbedding
Example:	`OfflineMode=True`
See Also:	ModelName

######## Script


Type:	String
Default:
Required:	Yes, when Type is set to `Lua` or `Python`
Configuration Section:	MyEmbedding
Example:	`Script=answerserver/scripts/embeddings_script.lua`
See Also:

######## Type

The type of model that you want to use to generate the embeddings. You can use one of the following options:

Transformer. Use a sentence transformer model. For this type of model, you must also set ModelName.
Lua. Define a Lua script that you want to use. For this type of model, you must also set Script.
Python. Define a Python script that you want to use. For this type of model, you must also set Script.

The method you use must produce vectors that are compatible with the vectors you use in the Content component.


Type:	String
Default:
Required:	Yes
Configuration Section:	MyEmbedding
Example:	`Type=Transformer`
See Also:

Remote System Configuration Parameters

This section describes the configuration parameters that you can use in Remote systems (systems where you set Type to Remote).

AnswerServer

The name of a configuration section that defines the location of the Answer Server that contains the data and full configuration for the answer system that you want to connect to as a remote system.

When you configure a remote answer system, Answer Server forwards any Ask actions that use the remote system to the associated remote Answer Server.

You configure the remote Answer Server either by setting AnswerServerHost and AnswerServerACIPort in the system configuration, or by setting AnswerServer to the name of a configuration section that contains the host and port information (see Remote Answer Server Configuration Parameters). The AnswerServer option might be useful if you have multiple remote answer systems that use the same Answer Server.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AnswerServer=RemoteServer1`
See Also:	Remote Answer Server Configuration Parameters

AnswerServerACIPort

The ACI port of the Answer Server that contains the data and full configuration for the answer system that you want to connect to as a remote system.

When you configure a remote answer system, Answer Server forwards any Ask actions that use the remote system to the associated remote Answer Server.

When you use AnswerServerACIPort to set the port of your remote Answer Server, you must also set AnswerServerHost to the host name or IP address of the remote Answer Server.

If you have multiple remote answer systems that use the same remote Answer Server, you can instead set AnswerServer to the name of a configuration section where you define the host and port details (see Remote Answer Server Configuration Parameters).


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AnswerServerACIPort=7000`
See Also:

AnswerServerGSSServiceName

The GSSAPI service name to use to connect to the remote Answer Server that you specify in AnswerServerHost. If you use the GSSAPI protocol for communication between Answer Server and other Knowledge Discovery components, this parameter describes the (Kerberos-defined) service name of remote Answer Server for this system.

IMPORTANT: If you set AnswerServerGSSServiceName, you must set AnswerServerHost to a fully qualified domain name (that is, you cannot use localhost, an IP address, or a host without the domain name, even if these values resolve to the correct server). Answer Server retrieves the Kerberos realm from the child server host name.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AnswerServerGSSServiceName=ANSWER02`
See Also:	AnswerServerACIPort AnswerServerHost

AnswerServerHost

The IP address or host name of the Answer Server that contains the data and full configuration for the answer system that you want to connect to as a remote system.

When you configure a remote answer system, Answer Server forwards any Ask actions that use the remote system to the associated remote Answer Server.

When you use AnswerServerHost to set the host of your remote Answer Server, you must also set AnswerServerACIPort to the ACI port for the remote Answer Server.

If you have multiple remote answer systems that use the same remote Answer Server, you can instead set AnswerServer to the name of a configuration section where you define the host and port details. See Remote Answer Server Configuration Parameters.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AnswerServerHost=server1.example.com`
See Also:	AnswerServerACIPort Remote Answer Server Configuration Parameters

AnswerServerSSLConfig

The configuration section in which you specify the configuration details for connecting to the remote Answer Server for this system, usually SSLOptionN. You must set this parameter to use SSL connections between components.

This parameter configures the SSL connection to the component that you configure by using AnswerServerACIPort and AnswerServerHost.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AnswerServerSSLConfig=SSLOption2`
See Also:	AnswerServerACIPort AnswerServerHost Secure Socket Layer Parameters

AnswerSystem

The name of the answer system on the remote Answer Server that this answer system refers to.

When you configure a remote answer system, Answer Server forwards any Ask actions that use the remote system to the associated remote Answer Server. When you specify a remote system directly in your Ask action, Answer Server uses the value of AnswerSystem to route the action.

You must also configure the host and port of the remote Answer Server, either by setting AnswerServerACIPort and AnswerServerHost in the system configuration, or by setting AnswerServer to the name of a configuration section that defines the host and port (see Remote Answer Server Configuration Parameters)


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AnswerSystem=AnswerBank`
See Also:

AskActionDefaults

The name of a configuration section that contains the default values for parameters to use in the Ask to the remote server.

When you set this parameter, you must also create a configuration section with this name.

In this section, you can set any Ask action parameters, and set the default value for this parameter, which Answer Server uses when it sends Ask actions to the remote Answer Server for this system.

For example, you might want to set a default value for the Timeout parameter to use for the remote server.

If the Ask action includes an explicit value for the parameter, it overrides the default that you set in this configuration.

TIP: You can also configure parameters that Answer Server passes through to any remote servers or child components by setting AllowedQueryParameters.


Type:	String
Default:
Required:	No
Configuration Section:	MySystem
Example:	`AskActionDefaults=FactbankAskParams [FactbankAskParams] Timeout=10`
See Also:

MyAgentTriggerParams Configuration Parameters

This configuration section describes parameters that you want to set in the queries that Answer Server sends to the Conversation Agentstore component.

In this section, you can set any Content component query parameters, and set a value that Answer Server must use when sending agent trigger queries to the Agentstore.

For example, you might want to configure the DatabaseMatch parameter to set it to a particular database in your Agentstore.

This configuration section allows you to override the default values for the Agentstore query parameters.

For more information about the query parameters, refer to the Content Component Help.

MyAskActionDefaultParams Configuration Parameters

A configuration section that contains the default values for parameters to use in the Ask to the remote Answer Server.

In this section, you can set any Ask action parameters, and set the default value for this parameter, which Answer Server uses when it sends Ask actions to the remote Answer Server for this system.

For example, you might want to set a default value for the Timeout parameter to use for the remote server.

If the Ask action includes an explicit value for the parameter, it overrides the default that you set in this configuration.

TIP: You can also configure parameters that Answer Server passes through to any remote servers or child components by setting AllowedQueryParameters.

Remote Answer Server Configuration Parameters

This section describes the configuration parameters that describe a remote Answer Server that you want to connect to. You can use this section when you have multiple remote answer systems that all refer to the same Answer Server.

ACIPort

The ACI port of the Answer Server that contains the data and full configuration for the answer system that you want to connect to as a remote system.

When you configure a remote answer system, Answer Server forwards any Ask actions that use the remote system to the associated remote Answer Server.


Type:	String
Default:
Required:	No
Configuration Section:	MyRemoteAnswerServer
Example:	`ACIPort=7000`
See Also:

GSSServiceName

The GSSAPI service name to use to connect to the remote Answer Server that you specify in Host. If you use the GSSAPI protocol for communication between Answer Server and other Knowledge Discovery components, this parameter describes the (Kerberos-defined) service name of remote Answer Server for this system.

IMPORTANT: If you set GSSServiceName, you must set Host to a fully qualified domain name (that is, you cannot use localhost, an IP address, or a host without the domain name, even if these values resolve to the correct server). Answer Server retrieves the Kerberos realm from the child server host name.


Type:	String
Default:
Required:	No
Configuration Section:	MyRemoteAnswerServer
Example:	`AnswerServerGSSServiceName=ANSWER02`
See Also:	ACIPort Host

Host

The IP address or host name of the Answer Server that contains the data and full configuration for the answer system that you want to connect to as a remote system.

When you configure a remote answer system, Answer Server forwards any Ask actions that use the remote system to the associated remote Answer Server.

When you use Host to set the host of your remote Answer Server, you must also set ACIPort to the ACI port for the remote Answer Server.


Type:	String
Default:
Required:	No
Configuration Section:	MyRemoteAnswerServer
Example:	`Host=server1.example.com`
See Also:	ACIPort

SSLConfig

This parameter configures the SSL connection to the component that you configure by using ACIPort and Host.


Type:	String
Default:
Required:	No
Configuration Section:	MyRemoteAnswerServer
Example:	`SSLConfig=SSLOption2`
See Also:	ACIPort Host Secure Socket Layer Parameters

MySpellingChecker Configuration Parameters

This section describes the configuration parameters that you can use to configure Answer Server to check spelling.

ACIPort

The ACI Port of the Content component to use to check spelling.


Type:	Integer
Default:
Required:	Required to check spelling
Configuration Section:	Any section that you specify with the parameter `SpellcheckEngine`
Example:	`SpellcheckEngine=MySpellingChecker [MySpellingChecker] Type=Content Host=localhost ACIPort=12345 LanguageType=englishUTF8`
See Also:	Type Host

Host

The host name or IP address of the Content component to use to check spelling.


Type:	String
Default:
Required:	Required to check spelling
Configuration Section:	Any section that you specify with the parameter `SpellcheckEngine`
Example:	`SpellcheckEngine=MySpellingChecker [MySpellingChecker] Type=Content Host=localhost ACIPort=12345 LanguageType=englishUTF8`
See Also:	Type ACIPort

LanguageType

The value to use for the LanguageType parameter, in Query actions that are sent to the Content component to check spelling.


Type:	String
Default:
Required:	Required to check spelling
Configuration Section:	Any section that you specify with the parameter `SpellcheckEngine`
Example:	`SpellcheckEngine=MySpellingChecker [MySpellingChecker] Type=Content Host=localhost ACIPort=12345 LanguageType=englishUTF8`
See Also:

Type

The type of component to use to check spelling. Set this parameter to one of the following values:

Content - a Content component. You must index documents to use to check spelling.


Type:	String
Default:
Required:	Required to check spelling
Configuration Section:	Any section that you specify with the parameter `SpellcheckEngine`
Example:	`SpellcheckEngine=MySpellingChecker [MySpellingChecker] Type=Content Host=localhost ACIPort=12345 LanguageType=englishUTF8`
See Also:	Host ACIPort

MyStatisticsDB Configuration Parameters

This section describes the configuration parameters that describe the statistics database that you use to store popularity information about your question equivalence classes for your Answer Bank system. See StatsStorage.

ConnectionString

The connection string to use to connect to the statistics database. Answer Server sends statistics about the popularity of your question equivalence classes to this database.

The connection string is passed on to the database, so you can use a connection string that works with any SQL client application.

NOTE: On Linux operating systems, remove the spaces in the connection string.

To use a statistics database, Enabled must be set to True (the default).

The database that you configure must exist, but Answer Server creates all the tables that it needs to store the statistics information. The database must also be able and configured to accept dates in ISO-8601 formats (that is, YYYY-MM-DD hh:mm:ss).


Type:	String
Default:
Required:	No
Configuration Section:	MyStatisticsDB
Example:	`ConnectionString=Driver=PostgreSQL ANSI(x64); Server=sql-host.mycompany.com; Port=5432; Database=statsdb; Uid=postgres;password=password;`
See Also:	Enabled

Enabled

Set Enabled to False if you do not want to store usage count information for your Answer Bank question equivalence classes in a database. In this case, Answer Server does not send any information to the database.

If you disable the statistics database, all question equivalence classes in your Answer Bank agentstore have a usage count of zero.

By default, Enabled is set to True, but you must provide the connection information for the database by setting ConnectionString.


Type:	Boolean
Default:	True
Required:	No
Configuration Section:	MyStatisticsDB
Example:	`Enabled=True`
See Also:

Service Actions

This section describes the service actions that you can send to the service.

Introduction to Service Actions
Service Actions

Introduction to Service Actions

Service actions return data about the service and allow you to control the service.

You must add the ServicePort configuration parameter to the [Service] section of the configuration file to enable the service port. You can use authorization roles to control which users can send service control and service status actions. See Authorization Roles Configuration Parameters.

Service actions use the following syntax:

http://Host:Port/action=ActionName&[Parameters]

where,


`Host`	The IP address or name of the machine hosting the service.
`Port`	The `ServicePort` specified in the `[Service]` section of the configuration file.
`ActionName`	One of the actions described in this section.
`Parameters`	One or more parameters that might be required by an action. You must percent-encode all parameter values.

For example:

http://12.3.4.56:40010/action=GetConfig

This action uses port 40010 to request the service’s configuration file settings.

Service Actions

This section describes the Service actions. When the service port is enabled, it accepts the following standard status and control actions.


ACIThreadStatus	Returns the status of the service threads.
Diagnostic	Creates a ZIP file that contains information useful for troubleshooting.
GetConfig	Returns the service configuration file settings.
GetLogStream	Returns a specific log stream for the service.
GetLogStreamNames	Returns the names of the log streams that have been set up for the service.
GetStatistics	Returns statistics for the service.
GetStatus	Returns the service status (running or stopped).
GetStatusInfo	Returns status information for the service (for example, the service product name and version number).
Stop	Stops the service.
ValidateConfig	Returns a list of any configuration errors such as repeated or unused configuration keys and sections.

ACIThreadStatus

Returns information about the activity of all the threads that the ACI service is using, including the number of accepted connections.

NOTE: This is a service status action that can be sent only by users that belong to an authorization role that allows the ServiceStatus standard role, or which enables the action explicitly. See Authorization Roles Configuration Parameters.

Example

http://12.3.4.56:9002/action=ACIThreadStatus

This action uses port 9002 to request the status of all the threads that the service is using. The service is located on a machine with the IP address 12.3.4.56.

Parameters

None

Diagnostic

The Diagnostic action creates a ZIP file for the service, which contains useful information for troubleshooting.

The information provided, and the level of detail in the files, varies for different services.

NOTE: This is a service control action that can be sent only by users that belong to an authorization role that allows the ServiceControl standard role, or which enables the action explicitly. See Authorization Roles Configuration Parameters.

Example

action=Diagnostic&file=C:/Diagnostics/Component1_19062012.zip

Parameters

The following action parameters are required.

Parameter	Description
File	The file name and path to the ZIP file to create.

This action accepts the following optional parameters.

Parameter	Description
Logs	The log files to include in the ZIP file.

GetConfig

The GetConfig action returns the service’s configuration file settings.

Example

action=GetConfig

Parameters

None.

GetLogStream

The GetLogStream action returns a specific log stream for the service.

Example

action=GetLogStream&Name=application.log&FromDisk=True&Tail=10

This action displays the first ten entries from the application log stream.

Required Parameters

The following action parameters are required.

Parameter	Description
Name	The name of the log stream you want to return. To retrieve a list of log stream names, use the GetLogStreamNames service action.

Optional Parameters

This action accepts the following optional parameters.

Parameter	Description
FromDisk	Specifies whether to read the log stream from disk or memory.
Tail	The number of lines from the log stream to return.

GetLogStreamNames

The GetLogStreamNames action returns the names of the log streams defined for the service.

Example

action=GetLogStreamNames

Parameters

None.

GetStatistics

The GetStatistics action returns statistics for the service.

Each statistic returns in an autn:stat XML element. This element contains the following attributes:


class	The group that the statistic belongs to. For example, `Service`.
autnid	The subgroup that the statistic belongs to. For example, `Documents`.
name	The name of the statistic.
metric	The type of statistic. This can have one of the following values: * 0 String * 1 Bytes * 2 Bytes per second * 3 per second * 4 percent * 5 count * 6 number * 7 timestamp * 8 seconds * 9 milliseconds * 10 maximum * 11 megabytes
value	The value of the statistic.

For example:

<autn:stat class="Service" autnid="Statistics" name="24HourRequestsPerSecond" metric="3" value="8.5" />

In this example, the statistic 24hourRequestsPerSecond has a value of 8.5 per second.

The following statistics return for all servers:

Class	Statistic	Description
[Service] Class
[Statistics]
	`ServiceDuration`	The number of seconds the service has been running.
	`10SecondResponseAverage`	The average service response time (in milliseconds) measured over the last 10 seconds.
	`10SecondRequestsPerSecond`	The number of requests to the service per second in the last 10 seconds.
	`10SecondRequests`	The number of requests to the service in the last 60 seconds.
	`60SecondResponseAverage`	The average service response time (in milliseconds) measured over the last 60 seconds.
	`60SecondRequestsPerSecond`	The number of requests to the service per second in the last 60 seconds.
	`60SecondPeakRequestsPerSecond`	The highest number of requests to the service over any 60 second period.
	`60SecondRequests`	The number of requests to the service in the last 60 seconds.
	`1HourResponseAverage`	The average service response time (in milliseconds) measured over the last hour.
	`1HourRequestsPerSecond`	The number of requests to the service per second in the last hour.
	`1HourPeakRequestsPerSecond`	The highest number of requests to the service over any 1 hour period.
	`1HourRequests`	The number of requests to the service in the last hour.
	`24HourResponseAverage`	The average service response time (in milliseconds) measured over the last 24 hours.
	`24HourRequestsPerSecond`	The number of requests to the service per second in the last 24 hours.
	`24HourPeakRequestsPerSecond`	The highest number of requests to the service over any 24 hour period.
	`24HourRequests`	The number of requests to the service in the last 24 hours.
	`RecentResponseAverage`	The average service response time (in milliseconds) from the time the last 10 second period finished to the current time.
	`RecentRequestsPerSecond`	The number of requests to the service per second from the time the last 10 second period finished to the current time.
	`RecentPeakRequestsPerSecond`	The highest number of requests to the service from the time the last 10 second period finished to the current time.
	`RecentRequests`	The number of requests to the service from the time the last 10 second period finished to the current time.
	`TotalRequests`	The total number of requests that were made to the service.

The following statistics return for specific components:

Class	Statistic	Description
[ACI] Class
---	---	---
[Action:`ActionName`]
	`Count`	The total number of `ActionName` actions that were sent to the service.
	`CountHadAnswers`	The total number of `ActionName` actions that received answers in the response.
	`Avg.Duration`	The average duration (in ms) of `ActionName` actions.
	`Shortest`	The shortest duration (in ms) of `ActionName` actions.
	`Longest`	The longest duration (in ms) of `ActionName` actions.
	`Avg.ResponseSize`	The average size of responses (in bytes) for `ActionName` actions.
	`Min.ResponseSize`	The minimum size of a response (in bytes) for `ActionName` actions.
	`Max.ResponseSize`	The maximum size of a response (in bytes) for `ActionName` actions.
[Licensing] Class
[Users]
	`Maximum`	The maximum number of users that can be set up for this service.
[Statistics] Class
[Users]
	`Users`	The number of users that has been set up for this service.

Example

action=GetStatistics

Parameters

None.

GetStatus

The GetStatus action returns the status of the service (running, paused, or stopping) and some current configuration settings.

Example

action=GetStatus

Action Parameters

None.

GetStatusInfo

The GetStatusInfo action returns status information for the service (for example, the service’s product name, version number and so on).

The action returns the following status information for the service:

Statistics	Description
[StatusInfo]
---	---
`ServiceStartTime`	The time the service started running (in epoch seconds).
`ServiceUtilsVersion`	The version of the service utilities.
`ServiceName`	The name of the service.
`ProductName`	The product name of the service.
`ProductVersion`	The version of the product.
`ProductBuild`	The build of the product.
`ServicePID`	The process ID of the service.
`ProductUID`	The user identifier of the service.
`ServiceStatus`	The status of the service (running or stopped).

Example

action=GetStatusInfo

Parameters

None.

Stop

The Stop action stops the service.

Example

action=Stop

vbalashi/answerserver-25.3-docs.md

Answer Server

Get Started With Answer Server

Introduction

Answer Server System Architecture

Answer Bank

Fact Bank

Passage Extractor

Passage Extractor LLM

Retrieval Augmented Generation

Conversation

Introduction

Answer Server System Architecture

Answer Bank

Fact Bank

Passage Extractor

Passage Extractor LLM

Retrieval Augmented Generation

Conversation

Introduction

Answer Server System Architecture

Answer Bank

Fact Bank

Passage Extractor

Passage Extractor LLM

Retrieval Augmented Generation

Conversation

Introduction

Answer Server System Architecture

Answer Bank

Fact Bank

Passage Extractor

Passage Extractor LLM

Retrieval Augmented Generation

Conversation

Introduction

Answer Server System Architecture

Answer Bank

Fact Bank

Passage Extractor

Passage Extractor LLM

Retrieval Augmented Generation

Conversation

Introduction

Answer Server System Architecture

Answer Bank

Fact Bank

Passage Extractor

Passage Extractor LLM

Retrieval Augmented Generation

Conversation

Introduction

Answer Server System Architecture

Answer Bank

Fact Bank

Passage Extractor

Passage Extractor LLM

Retrieval Augmented Generation

Conversation

Install and Set Up Answer Server

Install Answer Server

External Dependencies

Install a Component as a Service on Windows

Install a Component as a Service on Linux

systemd

System V

Configure Answer Server

General Configuration

Configure Answer Server Systems

Configure an Answer Bank System

Configure a Fact Bank System

Configure a Passage Extractor System

Configure a Passage Extractor LLM System

Configure a Conversation System

Configure a Remote System

Language Configuration

Answer Bank Language Configuration

Fact Bank and Passage Extractor Language Configuration

Use Synonyms to Expand Queries

Update Synonyms