> For the complete documentation index, see [llms.txt](https://docs.aisera.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aisera.com/aisera-platform/ai-automation-optimize-flow/ai-workflow-studio/building-workflows/using-workflow-actions/entity-summarization-actions.md).

# Entity Summarization Actions

Each of the following Actions is discussed in this topic:

* [Create App Token](#create-app-token)
* [Upsert Aisera Entity](#upsert-aisera-entity)
* [Update Ticket Prediction State](#update-ticket-prediction-state)
* [Tickets Summarize](#tickets-summarize)
* [Tickets Generate Answer](#tickets-generate-answer)
* [Persist Entity Summarization](#persist-entity-summarization)
* [Regenerate](#regenerate)
* [HashInput](#hashinput)
* [Fetch Field Predictions](#fetch-field-predictions)
* [Read Ticket Table](#read-ticket-table)

***

#### Create App Token

**Description:** The Create App Token action generates a short-lived application authentication token (`x-app-token`) scoped to a tenant, bot, and data source. The returned token can be passed to other actions that require an authenticated request to Aisera APIs, such as Tickets Summarize, Tickets Generate Answer, Persist Entity Summarization, Regenerate, HashInput, and Fetch Field Predictions.

**Configuration Parameters:** This action has no configuration parameters.

**Input:**

* **botId (Long, Optional):** The bot identifier the issued token should be scoped to. If not provided, the bot from the current execution context is used. – example: `12345`
* **payload (String, Optional):** The token-generation request body as a JSON String. It should include the entities the token will be bound to with the following format: `{"tenantId": "String tenant id", "dataSourceId": Number data source id, "externalSystemId": Number external system id, "botId": Number bot id}`. – example: `{"tenantId":"acme","dataSourceId":1483,"externalSystemId":-1,"botId":-1}`

{% hint style="info" %}
The token returned by this action is required by most entity-summarization actions. Pass its response (or the relevant field) as the `xAppToken` input of the downstream action.
{% endhint %}

**Output:**

* **success (Boolean):** Indicates whether the token creation was successful (`true`) or failed (`false`).
* **response (String):** The raw response as a String, containing the generated token or error details.
* **mapResponse (Map):** The response parsed as a map, providing structured access to the generated token and related metadata.

***

#### Upsert Aisera Entity

**Description:** The Upsert Aisera Entity action inserts or updates an Aisera entity (Ticket, User, Group, or CMDB CI) by submitting it to the standard ingestion pipeline. If an entity with the same identifier exists, it will be updated; otherwise, a new entity will be created. This is typically used in custom ingestion flows that produce entities outside the standard sync pipeline.

**Configuration Parameters:** This action has no configuration parameters.

**Input:**

* **jsonProto (String, Required):** The entity content as a JSON String that conforms to the Aisera proto schema for the selected `protoType`. For a Ticket this includes fields like `{"id": "String id", "entityIdentity": {"externalId": "String external id"}, "title": {"text": {"text": "String title"}}, "description": {"text": {"text": "String description"}}, "type": "Incident|Request|..."}`. For User, Group, or CmdbCI, provide the equivalent proto fields.
* **protoType (String, Required):** The type of Aisera entity being upserted. Must be one of `Ticket`, `User`, `Group`, or `CmdbCI` (case-insensitive). This selects how `jsonProto` is parsed. – example: `Ticket`
* **dataSourceId (Number, Optional):** Optional data source identifier. If omitted, the data source associated with the current bot in the execution context is used; if none is found, the value defaults to `-1`. – example: `42`

**Output:**

* **responseMsg (String):** A message describing the result of the upsert operation. Empty on success; contains an error message when the operation fails.
* **success (Boolean):** Indicates whether the upsert operation was successful (`true`) or failed (`false`).

***

#### Update Ticket Prediction State

**Description:** The Update Ticket Prediction State action records audit-trail activities for a ticket as it progresses through the Aisera auto-resolution pipeline (filter, prediction, applicable predictions, post-prediction, apply, inference). Each stage input describes whether that stage passed and produces a corresponding ticket-state update. When the `inference` input is provided, only the inference flow is recorded and earlier stages are skipped.

**Configuration Parameters:** This action has no configuration parameters.

**Input:**

* **botId (Long, Required):** The bot identifier the ticket belongs to. Required if not present in the execution context.
* **datasourceId (Long, Required):** The data source identifier the ticket belongs to.
* **ticketExternalId (String, Required):** The ticket identifier in the source system of record.
* **displayId (String, Required):** The user-visible display ID of the ticket in the source system. – example: `INC0010001`
* **ticketExtUri (String, Required):** The URL of the ticket in the source system, used for deep-linking in the audit record.
* **filter (String, Optional):** Result of the filter stage as a JSON String with the following format: `{"isSuccessful": Boolean, "message": "String reason if not successful", "additionalInformation": "String optional context message"}`.
* **prediction (String, Optional):** Result of the prediction stage as a JSON String with the following format: `{"isSuccessful": Boolean, "message": "String reason if not successful", "additionalInformation": "String optional context message"}`.
* **predictionApplied (String, Optional):** Result of the applicable-predictions stage as a JSON String with the following format: `{"isSuccessful": Boolean, "message": "String reason if not successful", "additionalInformation": "String optional context message"}`.
* **postPrediction (String, Optional):** Result of the post-prediction stage as a JSON String with the following format: `{"isSuccessful": Boolean, "message": "String reason if not successful", "additionalInformation": "String optional context message"}`.
* **action (String, Optional):** Result of the apply-to-SoR stage as a JSON String with the following format: `{"isSuccessful": Boolean, "isTriage": Boolean indicating triage vs. full resolution, "message": "String reason if not successful", "additionalInformation": "String optional context message"}`.
* **inference (String, Optional):** Result of the inference stage as a JSON String with the following format: `{"isSuccessful": Boolean, "isReopened": Boolean indicating the ticket has been reopened, "message": "String reason if not successful", "additionalInformation": "String optional context message"}`. When provided, the action runs only the inference flow and skips the earlier stages.

{% hint style="info" %}
The pipeline stages are processed in order until one returns `isSuccessful=false`. Provide only the stages your flow has actually executed.
{% endhint %}

**Output:**

* **success (Boolean):** Indicates whether the state update was published successfully (`true`) or failed (`false`).
* **response (String):** The result of the operation as a String, mirroring the success flag.

***

#### Tickets Summarize

**Description:** The Tickets Summarize action generates an LLM-based summary for a ticket using its title, description, and source-of-record identifiers. The result is either retrieved from cache or produced fresh when regeneration is requested. Useful when an agent or workflow needs a concise overview of a ticket to drive routing, escalation, or response generation.

**Configuration Parameters:** This action has no configuration parameters.

**Input:**

* **payload (String, Required):** The summarization request body as a JSON String with the following format: `{"externalId": "String source-of-record ticket id", "ticketExtId": "String source-of-record ticket id (alias)", "datasourceId": Number data source id, "title": "String ticket title to summarize", "description": "String ticket description/body to summarize", "regenerateCaseSummary": Boolean optional override to force regeneration}`. The `tenantId` and `botId` fields are automatically populated from the execution context.
* **botId (Number, Optional):** The bot identifier the summary should be scoped to. If not provided, the bot from the current execution context is used.
* **regenerate (String, Optional):** Query-string flag controlling cache behavior. When `"true"` the summary is regenerated even if a cached one exists; when `"false"` the cached summary is returned if available. – example: `false`
* **xAppToken (String, Optional):** Application authentication token (`x-app-token` header value) used to authorize the request. Typically obtained from the Create App Token action.

{% hint style="info" %}
Call Create App Token first and pass its result as `xAppToken`. Use Regenerate beforehand if you only want to refresh stale summaries.
{% endhint %}

**Output:**

* **success (Boolean):** Indicates whether the summarization request was successful (`true`) or failed (`false`).
* **response (String):** The raw response as a String, containing the generated ticket summary or error details.
* **mapResponse (Map):** The response parsed as a map, providing structured access to the generated summary and related metadata.

***

#### Tickets Generate Answer

**Description:** The Tickets Generate Answer action generates a retrieval-augmented (RAG) answer to a user's query by combining knowledge-base content with an LLM, optionally tied to a specific ticket. Cached answers are returned when available unless regeneration is requested. Useful in self-service flows where an automated answer should be drafted before involving an agent.

**Configuration Parameters:** This action has no configuration parameters.

**Input:**

* **payload (String, Required):** The answer-generation request body as a JSON String with the following format: `{"query": "String user query to answer", "externalId": "String source-of-record ticket id to associate the answer with (empty if not tied to a ticket)", "sessionVars": {Object containing optional session/context variables for the LLM}}`. The `tenantId` and `botId` fields are automatically populated from the execution context.
* **botId (Number, Optional):** The bot identifier the answer should be scoped to. If not provided, the bot from the current execution context is used.
* **regenerate (String, Optional):** Query-string flag controlling cache behavior. When `"true"` the answer is regenerated even if a cached one exists; when `"false"` the cached answer is returned if available. – example: `true`
* **xAppToken (String, Optional):** Application authentication token (`x-app-token` header value) used to authorize the request. Typically obtained from the Create App Token action.

**Output:**

* **success (Boolean):** Indicates whether the answer-generation request was successful (`true`) or failed (`false`).
* **response (String):** The raw response as a String, containing the generated answer or error details.
* **mapResponse (Map):** The response parsed as a map, providing structured access to the generated answer and related metadata.

***

#### Persist Entity Summarization

**Description:** The Persist Entity Summarization action persists a generated AI summary — ticket summary, generated answer, next best action, wrap-up, or field prediction — along with its supporting model insights so it can be retrieved and reused later without regenerating. Typically called after a Summarize, Generate Answer, or Fetch Field Predictions action to store the result for future use.

**Configuration Parameters:** This action has no configuration parameters.

**Input:**

* **payload (String, Required):** The persistence request body as a JSON String with the following format: `{"summarizationType": "String one of TICKET_SUMMARY | TICKET_ANSWER | NEXT_BEST_ACTION | TICKET_WRAP_UP | FIELD_PREDICTION", "externalId": "String source-of-record ticket id", "summary": "String stringified JSON of the generated summary/answer to store", "insights": "String stringified JSON of model debug/insights metadata", "inputHash": "String long hash of the inputs used to produce the summary (defaults to 0)", "sorUpdatedAt": "Optional timestamp of the source ticket's last update"}`.
* **xAppToken (String, Optional):** Application authentication token (`x-app-token` header value) used to authorize the request. Typically obtained from the Create App Token action.

{% hint style="info" %}
Use HashInput to produce the `inputHash` value so that the stored entry can later be detected as stale by Regenerate.
{% endhint %}

**Output:**

* **success (Boolean):** Indicates whether the persistence operation was successful (`true`) or failed (`false`).
* **response (String):** The raw response as a String, including confirmation of the persisted record or error details.
* **mapResponse (Map):** The response parsed as a map, providing structured access to the persistence result and any returned metadata.

***

#### Regenerate

**Description:** The Regenerate action checks whether a previously stored AI-generated summary or answer for a ticket needs to be regenerated. It returns `true` when the stored result is missing, the ticket has been updated since it was produced, or the input hash has changed. Use this action to short-circuit expensive AI calls when a cached result is still valid.

**Configuration Parameters:** This action has no configuration parameters.

**Input:**

* **payload (String, Required):** The regenerate-check request body as a JSON String with the following format: `{"id": "String external ticket id from the source system", "type": "String one of TICKET_ANSWER | TICKET_SUMMARY | NEXT_BEST_ACTION | TICKET_WRAP_UP | FIELD_PREDICTION", "inputHash": "String long hash of the ticket inputs used to detect content drift (defaults to 0)"}`.
* **xAppToken (String, Optional):** Application authentication token (`x-app-token` header value) used to authorize the request. Typically obtained from the Create App Token action.

**Output:**

* **success (Boolean):** Indicates whether the regenerate check was successful (`true`) or failed (`false`).
* **response (String):** The raw response as a String, containing the regenerate flag — example: `{"isRegenerate": true|false}`.

***

#### HashInput

**Description:** The HashInput action computes a stable numeric hash of a ticket's textual content (typically title, description, and comments) so callers can later detect whether the content has materially changed and a stored AI result needs to be refreshed. Pair this with Persist Entity Summarization and Regenerate to drive cache-invalidation logic.

**Configuration Parameters:** This action has no configuration parameters.

**Input:**

* **payload (String, Required):** The hash-input request body as a JSON String with the following format: `{"inputText": "String text to be hashed - typically the concatenation of ticket title, description and comments"}`.
* **xAppToken (String, Optional):** Application authentication token (`x-app-token` header value) used to authorize the request. Typically obtained from the Create App Token action.

**Output:**

* **success (Boolean):** Indicates whether the hash request was successful (`true`) or failed (`false`).
* **response (String):** The raw response as a String, containing the computed hash — example: `{"response": "<longHashString>"}`.

***

#### Fetch Field Predictions

**Description:** The Fetch Field Predictions action predicts values for ticket fields (e.g. priority, category, assignment group, configuration item) for a given object type (e.g. Incident, Case, Request) by running an ML model against the ticket's title and description. Predictions can be returned in test mode (not persisted) or in production mode (persisted for the ticket).

**Configuration Parameters:** This action has no configuration parameters.

**Input:**

* **payload (String, Optional):** The field-prediction request body as a JSON String with the following format: `{"ticketExtId": "String source-of-record ticket id - used to look up the ticket if title/description are blank", "title": "String ticket title to predict on (optional if ticketExtId resolves to an existing ticket)", "description": "String ticket description/body to predict on (optional if ticketExtId resolves to an existing ticket)"}`.
* **objectType (String, Optional):** The type of ticket object to predict fields for. Defaults to `"Incident"` if not provided. – example: `Incident`
* **isSync (String, Optional):** Flag indicating whether to run in test mode. When `"true"` predictions are returned but not persisted; when `"false"` predictions are persisted against the ticket. Defaults to `"false"`. – example: `false`
* **xAppToken (String, Optional):** Application authentication token (`x-app-token` header value) used to authorize the request. Typically obtained from the Create App Token action.

**Output:**

* **success (Boolean):** Indicates whether the prediction request was successful (`true`) or failed (`false`).
* **response (String):** The raw response as a String, containing the predicted field values or error details.
* **mapResponse (Map):** The response parsed as a map, providing structured access to the predicted field values and related metadata.

***

#### Read Ticket Table

**Description:** The Read Ticket Table action reads records from a table in a connected ticketing system (e.g. ServiceNow), returning a paginated list of rows with the requested columns. The exact set of supported tables, fields, and query syntax depends on the ticketing system that backs the configured data source.

**Configuration Parameters:** This action has no configuration parameters.

**Input:**

* **name (String, Required):** Name of the table to read from in the ticketing system. – example: `incident`
* **fields (String, Optional):** Comma-separated list of column names to return for each record. If omitted, all columns of the table are returned. – example: `sys_id, number, state, short_description`
* **query (String, Optional):** Filter query in the native query syntax of the ticketing system. For ServiceNow, this is an encoded query string. – example: `stateIN1,2^caller_id.emailIN=user@example.com^ORDERBYDESCsys_updated_on`
* **limit (Number, Optional):** Maximum number of records to return. Defaults to `100` when not provided. – example: `50`
* **offset (Number, Optional):** Zero-based offset of the first record to return, used for pagination. Defaults to `0`. – example: `0`
* **dataSourceId (Number, Optional):** Identifier of the data source representing the connected ticketing system to query. If omitted, the data source associated with the current bot in the execution context is used.

**Output:**

* **records (List of records):** A list of records returned from the table, each represented as a map of column name to value.