AI insights skill reference

  • Release version: Zurich
  • Updated January 27, 2025
  • 2 minutes to read

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