Google Docs enables you and your team to create, update and delete interactive documents online.

Google provides multiple ways of interacting with their products, one of them being webservice requests through an API. Good thing Betty Blocks rocks at webservices!

The base of all information shown here is derived from and can be found in Google's documentation hub: Google Docs API

In this article we'll show you: 

  • How to get an authentication token
  • How to use the authentication in requests
  • How to perform requests regarding Google Documents

Getting an Authorization token

Before we can send a request to Google regarding Docs, Sheets or any of the other services, we must get an authorization token.
It's because they have multiple services, they offer a centralized method to retrieve a token.

This means we have to execute an extra request. It also means we can reuse this flow for every Google webservice we're connecting with.

We created an article on its own which explains how to get a token from Google. Before starting with it, make sure to read up on Google's documentation about Google Docs, as you may need some specific information solely meant for our case that isn't actively discussed in the article. The article can be found here: Setting up Google OAuth2 Authentication

Sending requests to Google

If all went well, you were able to set up an authentication flow with the previous article. With that, you can call an object variable which is then used for authentication purpose in your actual Google request.

Google Docs Webservice

Let's start by creating the Google Docs webservice in your application. Enter the following values in the corresponding fields.

Name: Google Docs API
Protocol:
HTTPS
Host: docs.googleapis.com
Authentication Type: None
Request Content-Type:
JSON
Response Content-Type:
JSON
Headers:
Authorization

We're leaving the Authentication Type option on None, as we will be handling the authentication part through the Header variable Authorization. We will be selecting a variable containing the token from the previous chapter in our action.

Authorization

The value Google wants in the Authorization header should be in the format Bearer *access_token*. Because we don't receive the token in this format, we must create it ourselves. In our method, it's best to this on record level. 

Go to the model you're saving the OAuth2 Access tokens in and create a new Text expression (single line) property.

  • Type: Text expression (single line)
  • Name: Bearer token
  • Label: bearer_token
  • Expression: "Bearer " + var:record.access_token

This will make the required Authorization value available on each record. 

Go back to the Google Docs webservice and create an input variable to insert the authorization token record dynamically.

  • Kind: Text
  • Name: oauth_token

Now select the variable in the Authorization header. 

Every time you run a test on a webservice, you'll be prompted to enter a token. This token can be filled by entering it manually or adding an Object input variable on the action you're using the webservice endpoint on. If the most recent token is expired, reissue the token and try again.

Google Docs Webservice Endpoints

The Webservice we created above serves as a base for each request we will be executing. The actual request, which operations we're performing, is defined in the webservice's endpoints. Each operation gets its own endpoint. In this article we will be showing the following operations:

  • Create a new document
  • Get a document by ID
  • Update a document's content

In this article we'll be using a clean environment: no documents and no configurations whatsoever.

Create a new document

This request is used to create a new document in your Google Docs environment.
See Method: documents.create for more information about the request.
Enter the following values in the corresponding fields:

  • Name: Google Docs: Create new document
  • Http method: POST
  • Path: v1/documents
  • Request Content-Type: [inherit]
  • Response Content-Type: [inherit]

When executing the request like this, a blank document will be created. For this example, let's include a title. See Google's documentation about all possible values/options to include in a request.

Create a body variable called title.
Click Run test in the top-right corner and you'll be prompted to enter valid OAuth token and a title. Proceed and witness how a document is created. The response should look something like this: 

Feel free to generate a custom model based on the response. It actually makes it easier to use the response in the remainder of an action.

Get document by ID

This request is used to collect an existing document from your Google Docs environment based on an ID passed in the request.
See Method: documents.get for more information about the request.
Enter the following values in the corresponding fields:

  • Name: Google Docs: Get document by ID
  • Http method: GET
  • Path: "v1/documents/" + var:document_id 
  • Request Content-Type: [inherit]
  • Response Content-Type: [inherit]
  • Path variable:  var:document_id (is input variable)

When performing this request, the body must be empty. The value needed for var:document_id is the Document's identifier, which can be found in the url when viewing the article in Google Docs.

Click Run test in the top-right corner and you'll be prompted to enter valid OAuth token and a title. Proceed and witness how a document is created. The response should look something like this: 

Feel free to generate a custom model based on the response. It actually makes it easier to use the response in the remainder of an action.

In our case, we first created a document. The response of that request includes the new document's identifier. We saved that value in a record, so we can use it again. The action we're using this request in, is based on the model of said record. We can pass the var.record.identifier on to the input variable var:document_id.

The response will be made available through the custom model in var:document_response.

Update a document's content

This request is used to update an existing document from your Google Docs environment based on an ID passed in the request.
See Method: documents.batchUpdate for more information about the request.
Enter the following values in the corresponding fields:

  • Name: Google Docs: Update document by ID
  • Http method: POST
  • Path: "v1/documents/" + var:document_id + ":batchUpdate"  
  • Request Content-Type: [inherit]
  • Response Content-Type: [inherit]
  • Path variable:  var:document_id (is input variable)
  • Template: - New -

The value needed for var:document_id is the Document's identifier, which can be found in the url when viewing the article in Google Docs.

When performing this request, we must include a template containing the data to update our document. Open the newly created template on the right side of the form and enter a new name.

Google offers an example request template, which is as following:

Request template

{
  "requests": [
    {
      object(Request)
    }
  ],
  "writeControl": {
    object(WriteControl)
  }
}

Because it's possible to include multiple updates in one request, we must place our value in the object(Request) part.
What follows is an example of how to update a document with some text and an image:

Request Template

{
    "requests": [
        {
            "insertText": {
                "text": "This is the logo of Betty Blocks.",
                "location": {
                    "index": 1
                }
            }
        },
        {
            "insertInlineImage": {
                "location": {
                    "index": 34
                },
                "uri": "https://westfrieslandinbedrijf.nl/wp-content/uploads/2017/11/logo_bettyblocks.png"
            }
        }
    ]
}

The result of this request would be:

How to continue?

With examples of each request you can now move on to implement them in your workflows. This means you have to combine the requests. For example, if you want to update a value in a document, you must first know where it exactly is located.

  • Execute the Get document by ID request to receive an overview of the document. Each element is accompanied with an index, showing you its location.
  • Pass these index values on to the Update a document's content request. 
  • Delete the values/Insert new values on said index value(s).

Google provides a Best Practice guide on how to proceed here: Google Docs Best Practice

Did this answer your question?