Connecting SAP Build Process Automation to Google Workspace, so invoice PDFs arriving in a Gmail inbox land in a local folder, ready for extraction and approval.
Introduction
This is the fourth post in the series. In the first post, we built the core invoice approval workflow in SAP Build Process Automation (BPA). In the second, we connected to a trial Document AI instance, and in the third, we wired extraction straight into the approval process. Throughout, the invoice PDFs were simply sitting in a folder, put there by hand.
In practice, invoices arrive by email. So in this post we remove that last manual step: a task automation connects to Google Workspace, searches a Gmail inbox for invoice emails, and saves the PDF attachments into a folder on the machine running the Desktop Agent. That folder is then what the extraction and approval flow reads from.
Here’s what we’ll cover:
- Creating an OAuth 2.0 Client ID in Google Cloud Console
- Creating the External Authentication in BPA Control Tower
- Registering the authentication on the Desktop Agent and giving consent
- Building a task automation that searches Gmail and downloads attachments
- Testing it with a real email
Choosing How to Connect to Google Workspace
BPA offers a few ways to authorize against Google Workspace. Authorize Google (OAuth Client ID) and Authorize Google (Service Account) are activities placed inside the automation, and both work on Desktop Agent 2 and 3. Select Google Authentication works differently: the OAuth client is configured once in Control Tower, registered once on the Desktop Agent, and the automation simply selects it by name.
We’ll use Select Google Authentication, which requires Desktop Agent 3 (SAP documents version 3.16 or higher for Google external authorization). No credentials live inside the automation itself, which keeps the project clean.
Step 1: Set Up the OAuth Client in Google Cloud Console
Everything starts on the Google side. Open the Google Cloud Console and select the project you want to work in. Under APIs & Services, the Credentials page shows the OAuth consent screen, the Create credentials button, and any OAuth 2.0 Client IDs already created.
Â
APIs & Services > Credentials in the selected Google Cloud project.
- Enable the APIs. Under Enabled APIs & services, enable the Google Workspace APIs you plan to use. I enabled the Gmail API, Google Calendar API and Google Drive API. Only Gmail is used in this post, but the others save a trip back later.
- Configure the OAuth consent screen. On the Branding page of Google Auth Platform, give the app a name (mine is SAP-BPA-Test, which is what users see when they sign in) and a user support email.
Â
Branding — app name and user support email.
- Scroll down to the app domain fields and the developer contact email. The domain fields (home page, privacy policy, terms of service) can stay empty for a testing setup.
Â
Branding, continued — app domain, authorized domains and developer contact information.
- Set the Audience. I chose the External user type and left the publishing status as Testing. While in Testing, only listed test users can authorize the app, so add your own Gmail address under Test users.
Â
Audience — External user type, Testing status, and the test user list.
- Add scopes under Data Access. Scopes define what the app is allowed to do with the account. I added userinfo.email, cloud-platform, calendar, drive and the Gmail scope (https://mail.google.com/). Google groups Drive and Gmail under restricted scopes, which is why they get a stricter consent flow.
Â
Data Access — the non-sensitive, sensitive and restricted scopes added to the app.
- Create the client. Under Clients, create a new OAuth client with the application type Desktop app. I named mine Desktop Agent BPA. Google generates a Client ID and a Client secret, and you can also download them as a clientid.json file. Control Tower needs exactly these two values.
Â
The Desktop client — Client ID and client secret (sensitive parts hidden).
Treat the client secret like a password, and keep it out of screenshots and source control.
Step 2: Create the External Authentication in Control Tower
Now we move to SAP Build. From the Lobby, open Control Tower > External Authentication. This is where BPA stores the OAuth client details for the tenant. The screenshot below already shows one entry, Google Workspace Test, along with the Create New Authentication button.
Â
Control Tower > External Authentication.
- Choose Google as the type of external portal, then enter a unique Name (this is the name you’ll select in the automation later) and an optional Description.
- Paste the Client ID and Client Secret from the Google client (the clientid.json values).
- Select the scopes. User Email is pre-selected and mandatory. The list also offers Calendar, Cloud Platform, Drive and Gmail. I selected only Gmail for now, so the consent screen stays short and the permissions stay minimal. You can always create another authentication later with more scopes.
Â
The Create Authentication dialog for Google.
Step 3: Register It on the Desktop Agent
The authentication exists on the tenant, but it isn’t usable until the Desktop Agent on your machine registers it.
- In the Desktop Agent, click the Settings gear and choose External Authentication.
Â
Desktop Agent — Settings > External Authentication.
- The tenant’s authentications are listed with their type and status. Open the one you created.
Â
The external authentication listed in the Desktop Agent.
- Enter the email address of the Google account to use. You can mark the authentication as Default, so automations fall back to it when no name is given. Once it shows Registered, it can also be unregistered from this same screen.
Â
The registered authentication, with the email address hidden.
Registering opens Google’s sign-in flow in the browser. The first screen confirms which account is signing in to the app we named on the Branding page.
Â
Sign in with Google — confirming the account for SAP-BPA-Test.
The second screen lists what the app wants to access, which here is the Gmail permission we selected in Control Tower. Because the app is in Testing and unverified, Google’s wording is a bit more cautious. Review it and click Continue.
Â
The consent screen requesting Gmail access.
That’s the whole one-time setup. Any automation running on this Desktop Agent can now use the registered Google account.
Step 4: Build the Task Automation
With authorization in place, we can build the automation itself. I added a task automation, InvoiceApprovalAutomation, to the same project that holds the invoice approval process. For this post the flow is deliberately small: authenticate, search the inbox, clean the target folder, download the attachments, and log the result.
The Test Email
To test, I sent myself an email with a recognizable subject, Gmail-BPA, and three invoice PDFs attached. The automation searches for exactly that subject, so it only picks up emails meant for it.
Â
The test email in the Gmail inbox — three PDF attachments, ready to be read by the Desktop Agent.
Building the Flow
- Select Google Authentication. The first activity takes the name of the external authentication as its only input. Pick the one you registered (in my case, Google Workspace Test). If it’s left empty, the default registered authentication is used. The activity can throw a GoogleAuthError.
Â
Select Google Authentication — the name of the registered external authentication.
- Try / Catch. Everything that talks to Gmail sits inside a Try block that catches GmailError, so a failure (an expired token, for example) can be handled and logged rather than crashing the automation halfway.
Â
The Try block, catching GmailError.
- Search Emails (Gmail). The query is Label: Inbox subject:(“Gmail-BPA”), which looks in the inbox for messages with our keyword in the subject. The usual Gmail search operators work here, so you can narrow it further (for example with is:unread or has:attachment). includeSpamTrash is set to false, and the output, messageIdentifiers, is the list of matches.
Â
Search Emails (Gmail) — query on the inbox label and subject.
- Email Found? A Condition step checks messageIdentifiers.length > 0. If at least one email matches, the flow continues. Otherwise, the default branch just logs that nothing was found, which is a normal outcome for a scheduled run on an empty inbox.
Â
The Email Found? condition.
- Delete All Files. Before downloading, this activity empties the target folder (GmailFileFromAgent in my case), so attachments from earlier runs aren’t picked up by extraction a second time.
Â
Delete All Files — clearing the target folder before each run.
- Read Email (Gmail). This downloads the message. messageId is set to messageIdentifiers[0].messageId (the first match), location is fileSystem so the attachments are written to disk (the alternative is Google Drive), and pathOrDriveId is the folder we just cleaned. markAsRead is optional, and the output messageDetail holds the email details.
Â
Read Email (Gmail) — saving the attachments to the file system.
Running It
I ran the automation from the designer in unattended mode. The test console shows each step completing in order (Select Google Authentication, Search Emails, Delete All Files, Read Email, Log Message, End), and the target folder now holds the three PDF attachments from the test email.
Â
The test run, with the three invoice PDFs saved into the target folder.
The greyed-out steps lower in the flow (Get File Collection, the For Each loop, DocAI – Extract with Schema and InvoiceApprovalProcess) are disabled for this run. They’re the extraction and approval part from the earlier posts, which is where this folder gets used next.
Things to Keep in Mind
- One email per run. Because the message ID comes from index 0, this flow handles the first matching email. If several invoice emails can arrive between runs, loop over messageIdentifiers and use markAsRead so each is handled once.
- Testing-mode token expiry. For an External app in Testing status, Google limits how long a refresh token stays valid (documented as seven days). If the automation asks for authorization again after about a week, register the authentication on the Desktop Agent again. Publishing the app avoids this, but brings Google’s verification process into play, especially for the Gmail scope.
- Test users only. If Google blocks the sign-in, check that your account is on the Test users list.
- Scopes. If Gmail calls fail with permission errors, check that the Gmail scope was selected in the External Authentication, then unregister and register again so the new scope is granted.
Wrapping Up
Connecting BPA to Gmail takes a few moving parts: a Google OAuth client, an External Authentication in Control Tower, a registration on the Desktop Agent, and one activity in the automation. Once that’s done, it’s a reusable foundation. The same setup can later send emails (for example approval replies), change labels on processed mails, or work with Drive and Calendar if you add those scopes.
With invoice PDFs now landing in a folder straight from an inbox, the next step is to switch the extraction and approval steps back on, so that an email arriving in Gmail ends up as an approval task in My Inbox, and the decision goes back out by email, all from within the task automation.
Â
#abap