Integrate backend modules with your system

Backend modules is an out-of-the-box solution that provides an effective backend infrastructure to process large volumes of feature-related messages and interact with the agent desktop UI. This tutorial walks you through the process of integrating backend modules with your agent system.

For more information about background modules concepts and structure, see the backend modules basics documentation.

Prerequisites

Install the Google Cloud CLI if you haven't already configured it.

Set up environment variables

To make the commands for deployment simpler, we recommend that you set the following useful environment variables in your shell. You can set the variables using the following example command:

$ export GCP_PROJECT_ID='enter_project_id_here' \
&& export SERVICE_REGION='us-central1'

Set the following environment variables:

GCP_PROJECT_ID: The project ID of your Cloud Platform project that hosts related resources. Example: my-project.
SERVICE_REGION: The location or region of your services and related Cloud Platform resources. Example: us-central1.

Set up an administrative account

We recommend using separate Google Cloud accounts for service administration and runtime identity. Service administration is mainly performed by humans with Google accounts, while runtime identity grants Cloud Run services permissions using service accounts to enable access to necessary resources.

Prepare the human administrative account

If you plan to use an account that already has Editor or Owner permissions in your project, you can skip ahead to the next section.

To manage the backend infrastructure, establish an administrator account and grant it the following IAM roles. Their permissions are all included in the basic roles Editor (roles/editor) and Owner (roles/owner).

roles/secretmanager.admin (Secret Manager Admin): Manage secrets stored in Secret Manager for JWT generation and verification.
roles/run.admin (Cloud Run Admin): Deploy and manage Cloud Run services.
roles/iam.serviceAccountUser (Service Account User): Grant Cloud Run runtime service accounts iam.serviceAccounts.actAs permissions.
roles/cloudbuild.builds.editor (Cloud Build Editor): Build Docker images for the integration services using Cloud Build.
Artifact Registry Administrator: Store and manage built Docker images for the integration services.
roles/pubsub.editor (Cloud Pub/Sub Editor): Create and manage Cloud Pub/Sub topics and subscriptions.
roles/redis.admin (Redis Admin): Create and manage Memorystore for Redis' resources.

To grant IAM roles to a human account, use the add-iam-policy-binding Google Cloud CLI command. The following is an example command:

$ gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
 --member='user:[email protected]' \
 --role='roles/pubsub.editor'

Set the human administrative account in gcloud

Replace $ADMIN_ACCOUNT with the administrator account you would like to use (for example: [email protected]) in the following sample:

$ gcloud config set account $ADMIN_ACCOUNT

Set up service accounts

By default, Cloud Run services or jobs run as the default Compute Engine service account. Rather than leave the default, we recommend giving every Cloud Run service a dedicated identity by assigning it a user-managed service account with the minimum required set of permissions. If you plan to keep the default service account, you can skip ahead to set environment variables.

Create two service accounts for each Cloud Run runtime

To create the service accounts, replace the value of $CONNECTOR_SERVICE_ACCOUNT_ID and $INTERCEPTOR_SERVICE_ACCOUNT_ID if and run the following commands:

$ export CONNECTOR_SERVICE_ACCOUNT_ID='aa-ui-connector' && gcloud iam service-accounts create $CONNECTOR_SERVICE_ACCOUNT_ID
--description='Agent Assist integration - UI connector service account'
--display-name='Agent Assist integration - UI connector'

$ export INTERCEPTOR_SERVICE_ACCOUNT_ID='aa-pubsub-interceptor' && gcloud iam service-accounts create $INTERCEPTOR_SERVICE_ACCOUNT_ID
--description='Agent Assist integration - Pubsub interceptor service account'
--display-name='Agent Assist integration - Pubsub interceptor'

Use the following sample command to assign the following roles to the UI connector and Cloud Pub/Sub connector service accounts:

$ gcloud projects add-iam-policy-binding $GCP_PROJECT_ID 

--member='serviceAccount:$CONNECTOR_SERVICE_ACCOUNT_ID@$GCP_PROJECT_ID.iam.gserviceaccount.com' 

--role='roles/pubsub.editor'

Grant the following IAM roles to the UI connector service account:

roles/redis.editor
roles/vpcaccess.user
roles/compute.viewer
roles/secretmanager.secretAccessor
roles/dialogflow.agentAssistClient

Grant the following roles to the Cloud Pub/Sub connector service account:

roles/redis.editor
roles/vpcaccess.user
roles/compute.viewer

Set environment variables

Set the values of the following environment variables to be the service accounts you just created or the default Compute Engine service account in your project.

CONNECTOR_SERVICE_ACCOUNT: The service account for UI connector runtime. Example: [email protected].
INTERCEPTOR_SERVICE_ACCOUNT: The service account for Cloud Pub/Sub Interceptor runtime. Example: [email protected].

Customize the user authentication method

The code repository supports both backend users and users of the frontend module for Genesys Cloud and Twilio.

Within the code repository, open the ui_connector/auth.py file.
Specify the supported identity provider by setting the environment variable AUTH_OPTION or implement your authentication method with auth.check_auth.

By default, AUTH_OPTION is empty and no users are allowed to register JWT with the UI Connector service. Supported values:
- 'Salesforce': Verify the auth token using Salesforce OpenID Connect. Required environment variable: SALESFORCE_ORGANIZATION_ID.
- 'GenesysCloud': Verify the auth token using Genesys SDK UsersAPI.
- 'Twilio': Verify the auth token for Twilio. Required environment variable: TWILIO_FLEX_ENVIRONMENT.
Example:
```
$ export AUTH_OPTION='Salesforce'
```
Each token type might have a different means of validation. You decide how the token is validated. Without any changes, auth.check_auth returns false for every request.

Generate and store a JWT secret key

In order for the UI connector service to send secure authentication tokens back to the client, it must encrypt them using a JWT secret key. The key's value can be any arbitrary string, although it should be unique and difficult to guess.

This secret key will be stored in Secret Manager.

Set environment variable

JWT_SECRET_NAME: The name for the secret key in Secret Manager. It can be any arbitrary name. Recommended value: aa-integration-jwt-secret.

Generate the key

We recommend generating a random hash as the JWT secret key so that it cannot be guessed by attackers. To do so, you can use python secrets to generate secure random numbers for it.

Store the key in Secret Manager

In the following example command, replace my_key with the secret key you plan to use.

printf "my_key" | gcloud secrets create $JWT_SECRET_NAME --data-file=- --replication-policy=user-managed --locations=$SERVICE_REGION

Set up Memorystore for Redis

To set up Redis, you need the following environment variables:

VPC_CONNECTOR_NAME: The name of your Serverless VPC Access connector for connecting Cloud Run services to Memorystore for Redis. Recommended value: aa-integration-vpc.
VPC_NETWORK: The VPC network to attach your Serverless VPC Access connector to. The value should be default if you don't set up VPC for your Google Cloud project.
REDIS_IP_RANGE: An unreserved internal IP network for your Serverless VPC Access connector. A /28 of unallocated space is required. Recommended value: 10.8.0.0/28 (this value should work for most new projects).
REDIS_INSTANCE_ID: A name for your Redis instance. Recommended value: aa-integration-redis.

Create a Redis instance in the region of your Cloud Run services

Run the following command:

$ gcloud redis instances create $REDIS_INSTANCE_ID --size=5 --region=$SERVICE_REGION

Create a Serverless VPC Access connector

Ensure that the Serverless VPC Access API is enabled for your project:

$ gcloud services enable vpcaccess.googleapis.com

Create a Serverless VPC Access connector with a custom IP range:

$ gcloud compute networks vpc-access connectors create $VPC_CONNECTOR_NAME \
  --network $VPC_NETWORK \
  --region $SERVICE_REGION \
  --range $REDIS_IP_RANGE

Save the Redis host and Redis port as environment variables

Set the IP Address of your Redis instance to environment variable REDIS_HOST.
Set the port number of your Redis instance to environment variable REDIS_PORT.

Deploy the UI connector service

For the UI connector service, you need the following environment variables:

CONNECTOR_SERVICE_NAME: The Cloud Run service name of your UI Connector. Recommended value: ui-connector.
CONNECTOR_IMAGE_NAME: The image name of your UI Connector service. It can be the same as CONNECTOR_SERVICE_NAME. Recommended value: ui-connector.

Build the Docker image

Under the /ui-connector folder, run the following command:

$ gcloud builds submit --tag gcr.io/$GCP_PROJECT_ID/$CONNECTOR_IMAGE_NAME

Deploy UI connector to Cloud Run

Under the /ui-connector folder, run the following command. Make a note of the service URL for the deployed UI Connector, which will be used by clients (agent desktops).

$ gcloud run deploy $CONNECTOR_SERVICE_NAME \
--image gcr.io/$GCP_PROJECT_ID/$CONNECTOR_IMAGE_NAME \
--platform managed \
--service-account=$CONNECTOR_SERVICE_ACCOUNT \
--allow-unauthenticated \
--timeout 3600 \
--region $SERVICE_REGION \
--vpc-connector $VPC_CONNECTOR_NAME \
--set-env-vars REDISHOST=$REDIS_HOST,REDISPORT=$REDIS_PORT,GCP_PROJECT_ID=$GCP_PROJECT_ID \
--update-secrets=/secret/jwt_secret_key=${JWT_SECRET_NAME}:latest

Deploy Cloud Pub/Sub interceptor service

For the Pub/Sub interceptor service, you need the following environment variables:

INTERCEPTOR_SERVICE_NAME: The Cloud Run service name of your Cloud Pub/Sub interceptor. Recommended value: cloud-pubsub-interceptor.
INTERCEPTOR_IMAGE_NAME: The image name of your Cloud Pub/Sub interceptor service. It can be the same as INTERCEPTOR_SERVICE_NAME. Recommended value: cloud-pubsub-interceptor.

Build the Docker image

Under the /cloud-pubsub-interceptor folder, run the following command:

$ gcloud builds submit --tag gcr.io/$GCP_PROJECT_ID/$INTERCEPTOR_IMAGE_NAME

Deploy Pub/Sub interceptor to Cloud Run

Under the /cloud-pubsub-interceptor folder, run the following command:

$ gcloud run deploy $INTERCEPTOR_SERVICE_NAME \
--image gcr.io/$GCP_PROJECT_ID/$INTERCEPTOR_IMAGE_NAME \
--platform managed \
--service-account=$INTERCEPTOR_SERVICE_ACCOUNT_NAME \
--region $SERVICE_REGION \
--vpc-connector $VPC_CONNECTOR_NAME \
--ingress=internal \
# You can also add LOGGING_FILE here to specify the logging file path on Cloud Run. 
--set-env-vars REDISHOST=$REDIS_HOST,REDISPORT=$REDIS_PORT

Save the deployed URL

Set the deployed URL as the INTERCEPTOR_SERVICE_URL environment variable.

Configure Cloud Pub/Sub subscriptions

Cloud Pub/Sub subscriptions use the following:

Topics
Conversation profile
Service account
Service account permission for interceptor service
Conversation lifecycle events

Create Cloud Pub/Sub topics

Create a Cloud Pub/Sub topic for each kind of event notification you need from Dialogflow. The available event notification types are:

New suggestion events: Events sent when new Agent Assist suggestions are available (for example, new Smart Reply suggestions in response to a customer utterance).
New message events: Events sent whenever a new utterance is recognized from an agent or customer (for example, customer says Hi).
New conversation lifecycle events: Events sent for certain conversation lifecycle changes (for example, when a conversation is started, or when it is completed).

Make a note of the topic ID and topic name for later backend deployment.

Configure a conversation profile

Configure a conversation profile with the Cloud Pub/Sub topics that you created in the previous step.

When you create a new conversation profile, select Pub/Sub notifications and then Enable Pub/Sub notifications. Once enabled, you can check the boxes next to the types of notifications you'd like to enable and enter the topic ID for the notification's associated Cloud Pub/Sub topic.
Select JSON as the message format for each topic.

Create service account for Pub/Sub subscription identity

Create a service account representing the Pub/Sub subscription identity using the following command:

$ gcloud iam service-accounts create cloud-run-pubsub-invoker \
     --display-name "Cloud Run Pub/Sub Invoker"

Give the service account permission to invoke your interceptor service

Run the following command:

$ gcloud run services add-iam-policy-binding $INTERCEPTOR_SERVICE_NAME \ 
  --member=serviceAccount:cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com \
   --role=roles/run.invoker

Create Cloud Pub/Sub subscriptions for topics

For each topic that you created, you must create a corresponding Cloud Pub/Sub subscription.

New suggestion events

Replace your-new-suggestion-topic-id with the Cloud Pub/Sub topic you configured for new suggestions:

$ export TOPIC_ID='your-new-suggestion-topic-id' && gcloud pubsub subscriptions create $SUBSCRIPTION_NAME --topic $TOPIC_ID \
   --push-endpoint=$INTERCEPTOR_SERVICE_URL/human-agent-assistant-event \
   --push-auth-service-account=cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com

New message events

Replace your-new-message-event-topic-id with the Cloud Pub/Sub topic you configured for new message events:

$ export TOPIC_ID='your-new-message-event-topic-id' && gcloud pubsub subscriptions create $SUBSCRIPTION_NAME --topic $TOPIC_ID \
   --push-endpoint=$INTERCEPTOR_SERVICE_URL/new-message-event \
   --push-auth-service-account=cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com

Conversation lifecycle events

Replace your-conversation-lifecycle-event-topic with the Cloud Pub/Sub topic you configured for new conversation lifecycle events:

$ export TOPIC_ID='your-conversation-lifecycle-event-topic' && gcloud pubsub subscriptions create $SUBSCRIPTION_NAME --topic $TOPIC_ID \
   --push-endpoint=$INTERCEPTOR_SERVICE_URL/conversation-lifecycle-event \
   --push-auth-service-account=cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com