Integrating the assistant

This section covers integrating the Nextcloud assistant into the web frontend of other Nextcloud applications. For backend integration using the Task Processing OCP API, see Task Processing. For the OCS API, see Assistant OCS API.

Displaying a task result

There are two ways to display a task result using the assistant.

Browse the task result page

A standalone page is available at /apps/assistant/task/view/TASK_ID. It renders the same content as the assistant modal.

Running a task

Use OCA.Assistant.openAssistantForm to open the assistant modal from your application. The function accepts a single configuration object with the following keys:

`openAssistantForm` options
Key	Required	Description
`appId`	Yes	App ID of the calling application.
`customId`	No	Custom identifier for the task; useful when correlating the `task finished` backend event with the originating call. Defaults to `''`.
`taskType`	No	Initially selected task type (e.g. `core:text2text`, `speech-to-text`, `OCP\TextToImage\Task`). Defaults to the last used task type.
`input`	No	Object containing initial input values, specific to each task type. Defaults to `{}`.
`isInsideViewer`	No	Set to `true` if the function is called while the Viewer is open. Defaults to `false`.
`closeOnResult`	No	If `true`, the modal closes after a synchronous task completes and results are available. Defaults to `false`.
`actionButtons`	No	List of extra buttons to show in the result form. Only used when `closeOnResult` is `false`. Defaults to an empty list.

The function returns a Promise that resolves when the modal is closed — either because a task was scheduled, or a synchronous task ran and produced results. The promise resolves with a task object:

{
    appId: 'text',
    id: 310,
    customId: 'my custom identifier',
    input: { input: 'give me a short summary of a simple settings section about GitHub' },
    ocpTaskId: 152,
    output: { output: 'blabla' },
    status: 'STATUS_SUCCESSFUL',
    type: 'core:text2text',
    lastUpdated: 1711545305,
    scheduledAt: 1711545301,
    startedAt: 1711545302,
    endedAt: 1711545303,
    userId: 'janedoe',
}

Possible status values are: STATUS_UNKNOWN (0), STATUS_SCHEDULED (1), STATUS_RUNNING (2), STATUS_SUCCESSFUL (3), STATUS_FAILED (4).

Complete example:

OCA.Assistant.openAssistantForm({
    appId: 'my_app_id',
    customId: 'my custom identifier',
    taskType: 'core:text2text',
    inputs: { input: 'count to 3' },
    actionButtons: [
        {
            label: 'Label 1',
            title: 'Title 1',
            variant: 'warning',
            iconSvg: cogSvg,
            onClick: (output) => { console.debug('first button clicked', output) },
        },
        {
            label: 'Label 2',
            title: 'Title 2',
            onClick: (output) => { console.debug('second button clicked', output) },
        },
    ],
}).then(task => {
    console.debug('assistant promise success', task)
}).catch(error => {
    console.debug('assistant promise failure', error)
})

Populating input from a file

You can pre-fill a task input field with the content of a file by passing a fileId or filePath instead of a plain string value:

OCA.Assistant.openAssistantForm({
    appId: 'my_app_id',
    customId: 'my custom identifier',
    taskType: 'core:text2text',
    inputs: { input: { fileId: 123 } },
})

OCA.Assistant.openAssistantForm({
    appId: 'my_app_id',
    customId: 'my custom identifier',
    taskType: 'core:text2text',
    inputs: { input: { filePath: '/path/to/file.txt' } },
})

Integrating the assistant

Displaying a task result

Open the assistant modal

Browse the task result page

Running a task

Populating input from a file