AI insights skill reference

  • Release version: Zurich
  • Updated January 27, 2025
  • 2 minutes to read
    • Summarize
    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 skills that generate AI insights for the task details widget. These skills provide contextual information specific to task types and display insights in an AI response card on the task page. Administrators select the desired AI insights skill for a task type via the AI insights tab in thesnexsptaskconfigurationtable.

    Show full answer Show less

    The task details widget triggers your skill using the ActivityHubUtilSNC.generateAiInsights API when the task page loads. If no skill is selected, the AI insights section does not appear. Customers can also choose pre-built skills such as the out-of-the-box Approval summary checklist skill, which shows checklists only while approvals are actionable.

    Key Features

    • Custom skill input: Your skill receives the task record’s sysid and table name as input.
    • Custom skill output: Your skill must return a JSON structure including a mandatory summary string with HTML formatting and an optional array of references (each with number, title, and url) to display additional links.
    • Error handling: If the skill fails, it must return a JSON error response with status set to "error" and a message shown in the AI response card. Otherwise, a generic error message is displayed.
    • Performance considerations: Skills should be designed efficiently to avoid slowing down the task page.
    • Configuration: Administrators control when insights are generated using the property snexaiportal.taskinsightsgenmode, with options for automatic generation on page load or on-demand generation via user action.

    Practical Application

    ServiceNow customers can build AI insights skills tailored to specific task types to enhance task detail pages with relevant, contextual insights. Examples include:

    • Policy-check skills for Concur approval tasks
    • Contract Lifecycle Management (CLM) field-level insights for contract tasks
    • Time-off balance details for HR tasks

    By following the input/output contract and error handling guidelines, customers ensure consistent integration with the Now Assist framework and a seamless user experience.

    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

    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.

    To set a skill for a task type, see Configure a custom AI insights skill for a task type.

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

    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.

    Skill input specification

    Your skill receives the following payload.

    Table 1. Input fields
    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.

    Custom skill 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

    Return the following JSON structure from your skill, as a string or object:

    Table 2. Output fields
    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.

    Structure each object in your references array as explained in the following table:

    Table 3. Reference fields
    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.

    Error handling

    If your skill fails, return the following error structure:

    /b
    Table 4. Error response fields
    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.
    Note:
    If your skill returns an empty or unreadable response, the AI response card shows a generic error message instead.

    Configuration options

    Administrators control when your skill runs using this property:

    Table 5. Generation mode settings
    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.