Stay organized with collections Save and categorize content based on your preferences.
This page explains how to build a Google Workspace add-on that lets Google Docs users create resources, such as a support case or project task, in a third-party service from within Google Docs.
With a Google Workspace add-on, you can add your service to the @ menu in Docs. The add-on adds menu items that let users create resources in your service through a form dialog in Docs.
How users create resourcesTo create a resource in your service from within a Google Docs document, users type @ in a document and select your service from the @ menu:
When users type @ in a document and select your service, you present them with a card that includes the form inputs that users need in order to create a resource. After the user submits the resource creation form, your add-on should create the resource in your service and generate a URL that points to it.
The add-on inserts a chip into the document for the created resource. When users hold the pointer over this chip, it invokes the add-on's associated link preview trigger. Make sure your add-on inserts chips with link patterns that are supported by your link preview triggers.
Prerequisites Apps ScriptThis section explains how to set up resource creation for your add-on, which includes the following steps:
To configure resource creation, specify the following sections and fields in your add-on's manifest:
Under the addOns section in the docs field, implement the createActionTriggers trigger that includes a runFunction. (You define this function in the following section, Build the form cards.)
To learn about what fields you can specify in the createActionTriggers trigger, see the reference documentation for Apps Script manifests or deployment resources for other runtimes.
In the oauthScopes field, add the scope https://www.googleapis.com/auth/workspace.linkcreate so that users can authorize the add-on to create resources. Specifically, this scope allows the add-on to read the information that users submit to the resource creation form and insert a smart chip into the document based on that information.
As an example, see the addons section of a manifest that configures resource creation for the following support case service:
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview",
"https://www.googleapis.com/auth/workspace.linkcreate"
],
"addOns": {
"docs": {
"linkPreviewTriggers": [
...
],
"createActionTriggers": [
{
"id": "createCase",
"labelText": "Create support case",
"localizedLabelText": {
"es": "Crear caso de soporte"
},
"runFunction": "createCaseInputCard",
"logoUrl": "https://www.example.com/images/case.png"
}
]
}
}
}
In the example, the Google Workspace add-on lets users create support cases. Each createActionTriggers trigger must have the following fields:
To create resources in your service from the Docs @ menu, you must implement any functions that you specified in the createActionTriggers object.
When a user interacts with one of your menu items, the corresponding createActionTriggers trigger fires and its callback function presents a card with form inputs for creating the resource.
To create the card interface, you use widgets to display information and inputs that users need in order to create the resource. Most Google Workspace add-on widgets and actions are supported with the following exceptions:
updateCard navigation is supported.The following example shows an Apps Script callback function that displays a card when a user selects Create support case from the @ menu:
Apps Script Node.js Python JavaThe createCaseInputCard function renders the following card:
The card includes text inputs, a drop-down menu, and a checkbox. It also has a text button with anonClick action that runs another function to handle the submission of the creation form.
After the user fills out the form and clicks Create, the add-on sends the form inputs to theonClick action function–called submitCaseCreationForm in our example–at which point the add-on can validate the inputs and use them to create the resource in the third-party service.
After a user submits the creation form, the function associated with the onClick action runs. For an ideal user experience, your add-on should handle both successful and erroneous form submissions.
The onClick function of your add-on should create the resource in your third-party service and generate a URL that points to it.
In order to communicate the resource's URL back to Docs for chip creation, the onClick function should return a SubmitFormResponse with a one-element array in renderActions.action.links that points to a link. The link title should represent the title of the created resource and the URL should point to that resource.
The following example shows a SubmitFormResponse for a created resource:
After the SubmitFormResponse is returned, the modal dialog closes and the add-on inserts a chip into the document. When users hold the pointer over this chip, it invokes the associated link preview trigger. Make sure your add-on doesn't insert chips with link patterns not supported by your link preview triggers.
If a user tries to submit a form with invalid fields, instead of returning a SubmitFormResponse with a link, the add-on should return a render action that displays an error using an updateCard navigation. This lets the user see what they did wrong and try again. See updateCard(card) for Apps Script and updateCard for other runtimes. Notifications and pushCard navigations aren't supported.
The following example shows the code that's invoked when a user submits the form. If the inputs are invalid, the card updates and shows error messages. If the inputs are valid, the add-on returns a SubmitFormResponse with a link to the created resource.
The following code sample validates the form inputs and creates error messages for invalid inputs:
Apps Script Node.js Python Java Complete example: Support case add-onThe following example shows a Google Workspace add-on that previews links to a company's support cases and lets users create support cases from within Google Docs.
The example does the following:
https://www.example.com/support/cases/1234. The smart chip displays an icon, and the preview card includes the case name, priority, and description.$URL1 and $URL2 with the URLs of the functions for creating a third-party resource and creating a link preview. Code Apps Script Node.js Python
The following code shows how to implement a link preview for the created resource:
JavaThe following code shows how to implement a link preview for the created resource:
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-06 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-06 UTC."],[[["This guide details building a Google Workspace add-on to create and manage external resources (like support cases) directly within Google Docs."],["Users can create resources via a form within Docs, which then inserts a smart chip linking to the resource in the external service."],["The add-on requires configuration in the manifest file and utilizes Apps Script, Node.js, Python, or Java for development."],["Comprehensive code samples are provided to guide developers through card creation, form submission, and error handling."],["Smart chips representing the created resources offer link previews, enhancing user experience and information access."]]],[]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4