--- sourceDocument: Australia Employee Service Management sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/employee-service-management Release : - australia ft:locale : - en-US ft:publication_title : - Australia Employee Service Management ft:clusterId : - emplsm bundleId : - emplsm workflow : - Employee --- # AI insights skill info # AI insights skill reference {#ariaid-title1} Release version: Australia Updated January 27, 2025 ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 2 minutes to read Summarize ![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) Summarized using AI This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete. ## Summary of AI insights skill reference This reference guides ServiceNow customers on building custom Now Assist AI insights skills that generate contextual insights for the task details widget. Administrators select these skills via the AI insights skill field (aixaiinsightsskill) on the AI insights tab of thesnexsptaskconfigurationtable. When a task page loads, the task details widget invokes the skill throughActivityHubUtilSNC.generateAiInsightsto display AI-generated insights in the AI response card. Without a selected skill, the AI insights section remains hidden. Show full answer Show less Customers can use out-of-the-box skills like the Approval summary checklist generation skill or build custom skills tailored to specific task types, such as policy checks for approval tasks, contract lifecycle management insights, or time-off balance details. ## Skill Input and Output **Input:** Your custom skill receives a JSON payload containing: * **sysid**: The record identifier on the task page * **table**: The table name of the record on the task page **Output:** Your skill must return a JSON structure with: * **summary** (required): Insight text displayed in the AI response card, supporting HTML formatting * **references** (optional): An array of reference links, each including a number (optional), title, and URL to provide additional context ## Custom Skill Requirements and Error Handling * **Task context:** Design skills specific to the task type and available data. * **Performance:** Ensure efficient execution to avoid slowing the task page. * **Error handling:** On failure, return a JSON error with `status: "error"` and a user-friendly `message` to display in the AI response card. If the response is empty or unreadable, a generic error message appears. ## Configuration and Usage Administrators control if and when your skill runs by setting the **snexaiportal.taskinsightsgenmode** property: * **auto:** Insights generate automatically when the task page loads. * **ondemand:** Insights generate only when users select *Summarize this task*. These options allow flexible integration of AI insights tailored to organizational needs and user preferences. Build a custom Now Assist skill that generates AI insights for the task details widget. Use this reference for the input, output, and error contract your skill must follow. ## AI insights skill overview {#empworks-ai-insights-skill-ref__overview} Build your skill to match the input and output format in this topic. Administrators select your skill in the AI insights skill field (`aix_ai_insights_skill`) on the AI insights tab of the `sn_ex_sp_task_configuration` table. {#empworks-ai-insights-skill-ref__empworks-ai-insights-skill-ref-para-1} To set a skill for a task type, see [Configure a custom AI insights skill for a task type](https://servicenow-prod.fluidtopics.net/tLrAwrkLCSX1ugxnshi1KQ "Configure a task to use a custom Now Assist skill for AI insights in the Task details widget. Optionally add a custom script to pre-process input or post-process the skill response."). * When a task page loads, the task details widget runs your skill through `ActivityHubUtilSNC.generateAiInsights`. The widget then displays the results in the AI response card. * When a skill is not selected, the AI insights section doesn't appear. * Administrators can select the available skills such as the out-of-the-box Checklist Generation skill instead of building a custom one. For example, when you select the Approval summary checklist generation skill to show the approval checklist behavior, the checklist appears only while the approval (sysapproval_approver) is still actionable. Note: Approval checklist generation skill does not support other types of approvals. {#empworks-ai-insights-skill-ref__ul_zv2_2zt_5jc} ## Example use cases {#empworks-ai-insights-skill-ref__example-use-cases} Build a skill that helps you get the contextual insights and details relevant to the task type: * A policy-check skill for Concur approval tasks. * A skill that surfaces CLM field-level insights for contract tasks. * A skill that shows the time-off balance details. {#empworks-ai-insights-skill-ref__ul_mgx_j15_5jc} ## Skill input specification {#empworks-ai-insights-skill-ref__skill-input} Your skill receives the following payload. {#empworks-ai-insights-skill-ref__skill-input__entry__3} | Field | Type | Description | |-|-|-| | `sys_id` | String | The sys_id of the record on the task page. | | `table` | String | The table name of the record on the task page. | [Table 1. Input fields] ## Custom skill requirements {#empworks-ai-insights-skill-ref__skill-development-requirements} When you build custom skills, follow these guidelines Task context : Design your skill for the specific task type and the data available on that task. Performance : Make your skill execute efficiently so it does not slow the task page. Error handling : Handle failures using the format in error handling for your skill. ## Skill output specification {#empworks-ai-insights-skill-ref__skill-output} Return the following JSON structure from your skill, as a string or object: {#empworks-ai-insights-skill-ref__skill-output__entry__4} | Field | Type | Required | Description | |-|-|-|-| | `summary` | String | Yes | The insight text shown in the AI response card. Supports HTML formatting. | | `references` | Array | No | List of reference links. Each entry includes `number`, `title`, and `url` fields. | [Table 2. Output fields] Structure each object in your `references` array as explained in the following table: {#empworks-ai-insights-skill-ref__skill-output__entry__16} | Field | Type | Required | Description | |-|-|-|-| | `number`(Optional) | String | Yes | Reference identifier displayed in the card. | | `title` | String | Yes | Link text displayed to users. | | `url` | String | Yes | Target URL for the reference link. | [Table 3. Reference fields] ## Error handling {#empworks-ai-insights-skill-ref__error-handling} If your skill fails, return the following error structure: /b{#empworks-ai-insights-skill-ref__error-handling__entry__4} | Field | Type | Required | Description | |-|-|-|-| | `status` | String | Yes | Must be set to `error`. | | `message` | String | Yes | Error message displayed to users in the AI response card. | [Table 4. Error response fields] Note: If your skill returns an empty or unreadable response, the AI response card shows a generic error message instead. ## Configuration options {#empworks-ai-insights-skill-ref__configuration-options} Administrators control when your skill runs using this property: {#empworks-ai-insights-skill-ref__configuration-options__entry__3} | Property | Value | Behavior | |-|-|-| | `sn_ex_ai_portal.task_insights_gen_mode` | `auto` | Insights are generated automatically when the task page loads. | | `sn_ex_ai_portal.task_insights_gen_mode` | `on_demand` | Insights are generated when you select Summarize this task to generate insights. | [Table 5. Generation mode settings] **Related tasks** * [Configure a custom AI insights skill for a task type](https://servicenow-prod.fluidtopics.net/tLrAwrkLCSX1ugxnshi1KQ "Configure a task to use a custom Now Assist skill for AI insights in the Task details widget. Optionally add a custom script to pre-process input or post-process the skill response.")