Manage projects with Google Chat, Vertex AI, and Firestore

This tutorial shows how to make a Google Chat app that a team can use to manage projects in real time. The Chat app uses Vertex AI to help teams write user stories (which represent features of a software system from the point of view of a user for the team to develop) and persists the stories in a Firestore database.

Prerequisites

• A Google Workspace account with access to Google Chat.

• Access to Google Cloud services to do the following:

  • Create a Google Cloud project.
  • Link a Google Cloud billing account to the Cloud project. To learn if you have access, see Permissions required to enable billing.

  • Use unauthenticated Google Cloud Function invocations, which you can verify by determining whether your Google Cloud organization uses domain restricted sharing.

  If necessary, ask your Google Cloud administrator for access or permission.

• If using the Google Cloud CLI, a Node.js development environment configured to work with gcloud CLI. See Setting up a Node.js development environment.

Objectives

• Build a Chat app that manages agile software projects.
• Help users write user stories with generative AI-assisted story writing tools powered by Vertex AI:
  • Generate and regenerate story descriptions.
  • Expand story descriptions from notes to complete requirements.
  • Correct grammar to fix typos.
• Keep work up-to-date by writing to, and reading from, a Firestore database.
• Facilitate collaboration in a Chat space by letting users create, edit, assign, and start stories directly from the conversation.

Products used

The project management app uses the following Google Workspace and Google Cloud products:

• Chat API: An API for developing Google Chat apps that receive and respond to Chat interaction events, like messages. The project management Google Chat app uses Chat API to receive and respond to interaction events sent by Chat, and to configure attributes that determine how it appears in Chat, like name and avatar image.
• Vertex AI API: A generative AI platform. The project management Google Chat app uses the Vertex AI API to write user story titles and descriptions.
• Firestore: A serverless document database. The project management Google Chat app uses Firebase to store data about user stories.

• Cloud Functions: A lightweight serverless compute service that lets you create single-purpose, standalone functions that can respond to Chat interaction events without the need to manage a server or runtime environment. The project management Google Chat app uses Cloud Functions to host the HTTP endpoint that Chat sends interaction events to and as a compute platform to run logic that processes and responds to these events.

  Cloud Functions uses the following Google Cloud products to build, process interaction events, and host compute resources:

  • Cloud Build: A fully managed continuous integration, delivery and deployment platform that runs automated builds.
  • Pub/Sub: An asynchronous and scalable messaging service that decouples services that produce messages from services that process those messages.
  • Cloud Run Admin API: A fully managed environment for running containerized apps.

Architecture

The project management Google Chat app architecture receives and processes Chat interaction events at an HTTP endpoint, uses Vertex AI to help write user stories, and stores user story details in a Firestore database. The following diagram shows the architecture of the Google Workspace and Google Cloud resources used.

The project management Google Chat app works like this:

1. A user sends a message in Chat and invokes the project management Google Chat app by either messaging it directly, mentioning it in a space, or entering a slash command.

2. Chat sends a synchronous HTTP request to the Cloud Function's HTTP endpoint.

3. The project management Google Chat app processes the HTTP request:

   1. Vertex AI helps write or update a user story.

   2. A Firestore database stores, retrieves, updates, or deletes user story data.

4. Cloud Functions returns an HTTP response to Chat which displays it to the user as either a message or dialog.

Prepare the environment

This section shows how to create and configure a Google Cloud project for the Chat app.

Create a Google Cloud project

Google Cloud console

1. In the Google Cloud console, go to Menu menu > IAM & Admin > Create a Project.

   Go to Create a Project

2. In the Project Name field, enter a descriptive name for your project.

   Optional: To edit the Project ID, click Edit. The project ID can't be changed after the project is created, so choose an ID that meets your needs for the lifetime of the project.

3. In the Location field, click Browse to display potential locations for your project. Then, click Select.
4. Click Create. The Google Cloud console navigates to the Dashboard page and your project is created within a few minutes.

gcloud CLI

In one of the following development environments, access the Google Cloud CLI (`gcloud`):

• Cloud Shell: To use an online terminal with the gcloud CLI already set up, activate Cloud Shell.
  Activate Cloud Shell
• Local Shell: To use a local development environment, install and initialize the gcloud CLI.
  To create a Cloud project, use the `gcloud projects create`command:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID by setting the ID for the project you want to create.

Enable billing for the Cloud project

Google Cloud console

1. In the Google Cloud console, go to Billing. Click Menu menu > Billing > My Projects.

   Go to Billing for My Projects

2. In Select an organization, choose the organization associated with your Google Cloud project.
3. In the project row, open the Actions menu (more_vert), click Change billing, and choose the Cloud Billing account.
4. Click Set account.

gcloud CLI

1. To list available billing accounts, run:

   gcloud billing accounts list

2. Link a billing account with a Google Cloud project:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   Replace the following:

   • PROJECT_ID is the Project ID for the Cloud project for which you want to enable billing.
   • BILLING_ACCOUNT_ID is the billing account ID to link with the Google Cloud project.

Enable the APIs

Authentication and authorization

No authentication and authorization configuration is necessary to follow this tutorial.

To call the Firestore and Vertex AI APIs, this tutorial uses Application Default Credentials with the default service account attached to the Cloud Function, which you don't need to set up. In the context of a production environment, you would typically create and attach a service account to the Cloud Function instead.

Create and deploy the Google Chat app

Now that your Google Cloud project is created and configured, you're ready to build and deploy the Google Chat app. In this section, you do the following:

1. Create a Firestore database in which to persist and retrieve user stories.
2. Optionally, review the sample code.
3. Create a Cloud Function to host and run the Chat app's code in response to events received from Chat as HTTP requests.
4. Create and deploy a Google Chat app on the Google Chat API configuration page.

Create the Firestore database

In this section, you create a Firestore database to persist and retrieve user stories, but you don't define the data model. The data model is set implicitly in the sample code by the model/user-story.js and model/user.js files.

The project management Chat app database uses a NoSQL data model based on class documents organized into collections_bookmark collections. To learn more, see Firestore data model.

The following diagram is an overview of the project management Google Chat app's data model:

The root collection is spaces, where each document represents a space that the Chat app created stories in. Each user story is represented by a document in the userStories subcollection, and each user is represented by a document in the users subcollection.

Here's how to create the Firestore database:

Review the sample code

Optionally, before creating the Cloud Function, take a moment to review and familiarize yourself with the sample code hosted on GitHub.

View on GitHub

Here's an overview of each file:

env.js

Environment configuration variables to deploy the Chat app to a specified Google Cloud project and region. You must update the configuration variables in this file.

package.json and package-lock.json

Node.js project settings and dependencies.

index.js

Entry point for the Chat app's Cloud Function. It reads the Chat event from the HTTP request, calls the app handler, and posts the HTTP response as a JSON object.

controllers/app.js

The main application logic. Processes the interaction events by handling the Chat app mentions and slash commands. To respond to card clicks, it calls app-action-handler.js.

controllers/app-action-handler.js

Application logic to handle card click Chat interaction events.

services/space-service.js, services/user-service.js, and services/user-story-service.js

These files contain the parts of the application logic specific to working with Chat spaces, users, and user stories. The functions in these files are called by app.js or app-action-handler.js. To perform database operations, the functions in these files call functions in firestore-service.js.

services/firestore-service.js

Handles database operations. The functions in this file are called by services/space-service.js, services/user-service.js, and services/user-story-service.js.

services/aip-service.js

Calls the Vertex AI API for generative AI text prediction.

model/*.js

These files contain the definition of classes and enums that the application services use to store and pass data between functions. They set the data model for the Firestore database.

views/*.js

Each file in this directory instantiates a card object that the Chat app then sends back to Chat as either a card message or a dialog action response.

views/widgets/*.js

Each file instantiates a type of widget object that the app uses to build the cards in the views/ directory.

test/**/*.test.js

Each file in this directory and its subdirectories contains the unit tests for the corresponding function, controller, service, view, or widget. You can execute all the unit tests by running npm run test while in the project's root directory.

Create and deploy the Cloud Function

In this section, you create and deploy a Cloud Function that comprises the project management Chat app's application logic.

The Cloud Function runs in response to an HTTP request from Chat containing a Chat interaction event. When run, the Cloud Function code processes the event and returns a response to Chat which Chat renders as a message, dialog, or other type of user interaction. If applicable, the Cloud Function also reads from, or writes to, the Firestore database.

Here's how to create the Cloud Function:

1. When the function finishes deploying, copy the url property from the response. This is the Trigger URL that you use in the following section to configure the Google Chat app.

Configure the Google Chat app in the Google Cloud console

This section shows how to configure the Chat API in the Google Cloud console with information about your Chat app, including the Chat app's name, supported slash commands, and the trigger URL of the Chat app's Cloud Function to which it sends Chat interaction events.

1. In the Google Cloud console, click Menu menu > More products > Google Workspace > Product Library > Google Chat API > Manage > Configuration.

   Go to Chat API configuration

2. In App name, type Project Manager.

3. In Avatar URL, type https://developers.google.com/chat/images/quickstart-app-avatar.png.

4. In Description, type Manages projects with user stories.

5. Click the Enable Interactive features toggle to the on position.

6. Under Functionality, select Receive 1:1 messages, Join spaces and group conversations.

7. Under Connection settings, select App URL.

8. In App URL, paste the Trigger URL you copied from the Cloud Functions deployment, formatted as https://REGION-PROJECT_ID.cloudfunctions.net/project-management-tutorial. If you deployed the Cloud Function with the gcloud CLI, this is the url property.

9. Register the Chat app's slash commands. To register a slash command:

   1. Under Slash commands, click Add a slash command.

   2. For each slash command detailed in the following table, enter the Name, Command ID, Description, and select whether the slash command Opens a dialog, then click Done:

      Name	Command ID	Description	Opens a dialog
      /createUserStory	1	Create a story with the specified title.	Unselected
      /myUserStories	2	Lists all the stories assigned to the user.	Unselected
      /userStory	3	Displays current status of the specified story.	Unselected
      /manageUserStories	4	Opens a dialog where stories can be edited.	Selected
      /cleanupUserStories	5	Deletes all stories in the space.	Unselected

10. Under Visibility, select Make this Chat app available to specific people and groups in your Workspace domain and enter your email address.

11. Optionally, under Logs, select Log errors to Logging.

12. Click Save. A configuration saved message appears, meaning the Chat app is ready to test.

Test the Chat app

Test the project management Chat app by messaging it and using its slash commands to create, edit, and delete user stories.

1. Open Google Chat using the Google Workspace account that you provided when you added yourself as a trusted tester.

   Go to Google Chat

2. Click add New chat.
3. In the Add 1 or more people field, type the name of your Chat app.

4. Select your Chat app from the results. A direct message opens.

5. In the new direct message with the app, type Hello and press enter. The project management Chat app responds with a help menu detailing what it can do.
6. To create a story, type /createUserStory Test story in the message bar and send it. The project management Chat app responds with a card message detailing the user story it creates for you using generative AI from Vertex AI.

7. In the console, check the Firestore database to review the records it created about the space you added the Chat app to, the users who have interacted with it, and the user story you created.

   Go to Firestore

8. Return to Google Chat.

   Go to Google Chat

9. Optionally, to edit the story, click Edit. When you're satisfied with the story, click Save.
10. Test each slash command supported by the app. To see them, type / or mention the Chat app.
11. Delete the test user story by issuing the /cleanupUserStories slash command. Alternatively, remove or uninstall the app. When removed, the app deletes all user stories created in that space.

Troubleshoot

When a Google Chat app or card returns an error, the Chat interface surfaces a message saying "Something went wrong." or "Unable to process your request." Sometimes the Chat UI doesn't display any error message, but the Chat app or card produces an unexpected result; for example, a card message might not appear.

Although an error message might not display in the Chat UI, descriptive error messages and log data are available to help you fix errors when error logging for Chat apps is turned on. For help viewing, debugging, and fixing errors, see Troubleshoot and fix Google Chat errors.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, we recommend that you delete the Cloud project.

1. In the Google Cloud console, go to the Manage resources page. Click Menu menu > IAM & Admin > Manage Resources.

   Go to Resource Manager

2. In the project list, select the project you want to delete and then click Delete delete.
3. In the dialog, type the project ID and then click Shut down to delete the project.

Related topics

• Answer questions based on Chat conversations with a Gemini AI Chat app
• Respond to incidents with Google Chat, Vertex AI, and Apps Script