Getting Started with Honeycode APIs

Honeycode APIs

Amazon Honeycode has 12 Application Programming Interfaces (APIs) to let you programmatically interact with Honeycode apps and tables. You can use these APIs so that Honeycode can work with external applications and services to read, write, update, or delete data stored in Honeycode workbooks. In addition to this article, further Honeycode API Documentation can be found here.

App screen APIs

  • GetScreenData
  • InvokeScreenAutomation

Table metadata APIs

  • ListTables
  • ListTableColumns

Table row operation APIs

  • ListTableRows
  • QueryTableRows
  • BatchCreateTableRows
  • BatchUpdateTableRows
  • BatchUpsertTableRows
  • BatchDeleteTableRows

Import data APIs

  • StartTableDataImportJob
  • DescribeTableDataImportJob

Connecting Honeycode to AWS

The AWS Management Console is where you can connect Amazon Honeycode to AWS. The console enables you to connect a Honeycode team to an AWS account and upgrade or downgrade your team plans.

If you do not have an AWS account, start by creating one. Once you have an AWS account, you can connect it to Honeycode by following these instructions.

AWS Software Developer Kit (SDK)

The AWS Software Development Kit (SDK) is a software library that enables you to interact with AWS Application Programming Interfaces (APIs). The AWS SDK supports Amazon Honeycode APIs. To use the SDK you will need to connect your Amazon Honeycode team to an AWS account.

Identity and Access Management (IAM)

AWS Identity and Access Management (IAM) is a service that helps you securely control access to AWS resources. You can use IAM to control who is authenticated (signed in) and authorized (has permissions) to use resources.


App screen APIs

Setting up for app screen APIs

To use Amazon Honeycode App Screen APIs you’ll need to first create a table and add some data. Then build an app and add a screen specific to each API action or automation. Although you can use any app for this purpose, we recommend you create an app solely for API access.

Create a table

You will need a workbook with tables to set up APIs. If you haven’t already done so, create a new workbook and add a new table either by importing a CSV file or by adding data manually. In the example below, we start with a simple tasks table.

Task table

Build your app

Building an app will be necessary for the InvokeScreenAutomation and GetDataScreen APIs. Open Honeycode Builder from the left navigation, click the + and select “Build your own.” Formatting, font, and colors aren’t important for this app, so you can leave the app styling as default, if you wish.

Name your app objects

The InvokeScreenAutomation and GetDataScreen APIs APIs return the names of blocks and data cells, along with the values of data cells. Be thoughtful as you name your objects as they are visible in the API response.

ARNs and Honeycode IDs

Amazon Resource Names (ARNs) uniquely identify AWS resources and are required for many actions related to IAM policies and API calls.

Accessing ARN and IDs

In any app screen, you can right-click to bring up a menu. Select Get ARN and IDs.

Access ARN IDs

From the modal that appears, you can copy the ARN and IDs for the workbook, app, and screen.

Get ARN and ID


ARNs and authorization

If you are using the managed IAM policies AmazonHoneycodeWorkbookFullAccess or AmazonHoneycodeFullAccess , you will not need the ARN for authorization. The ARN is only required to to set up authorization using IAM at a granular level.


Configuring app screens

There are many ways you can configure your app, but here we’ll show you how to set up screens for some common actions that you can use APIs to execute.

For the examples below, we used the managed policy, AmazonHoneycodeWorkbookFullAccess .

To read data

Based on the Tasks table above, let’s say you want to read items filtered by the Status column. Here’s an example of one way to set up a screen that allows you to use the GetScreenData API to read screen data programatically.

  • Insert a Column list object, which can include a preconfigured filter

  • Choose to filter by the Status column =$[Status filter]

  • Make the =$[Status filter] data cell editable, if it isn’t already

  • Check that the list source is set to =FILTER(Tasks,"(Tasks[Status]=$[Status filter] OR $[Status filter]="""")")

  • Confirm that both data cells in the list shared, and set the sources to the Tasks column and the Status column

Note: The Column list is a preconfigured app object that includes some UI features not shown in the image above.


To add a row

If you want to manipulate data using the InvokeScreenAutomation API to add rows, then set up the screen and corresponding button in your app.

  • Add variable data cells and name them Task and Status

  • Make the data cells editable

  • To add the automation, select the button and click on the Actions tab in the button properties panel

  • Configure your automation to take data from the variable data cell =$[Tasks] and write it to the Tasks column

  • Repeat the automation for the variable data cell =$[Status]


To overwrite a row

If you want to manipulate data using the InvokeScreenAutomation API to overwrite existing rows, then set up the screen and corresponding button in your app.

  • Add a variable data cell, make it editable, and name it Row

  • Under the Display tab, format the data cell as a rowlink and set the source as the Tasks table

  • Add a block and set the data source as the variable data cell =$[Row]

  • Add a variable data cell, name it Task, make it editable, and set the data source to the Task column =[Task]

  • Repeat the above step, naming it Status and setting the data source to to the Status column =[Status]

  • To add the automation, select the button and click on the Actions tab in the button properties panel

  • Configure your automation to take data from the variable data cell =$[Tasks] and overwrite the old data with the new data in the Tasks column

  • Repeat the automation for the variable data cell =$[Status]


To delete a row

If you want to manipulate data using the InvokeScreenAutomation API to delete existing rows, then set up the screen and corresponding button in your app.

  • Add a variable data cell, make it editable, and name it Row
  • Under the Display tab, format the data cell as a rowlink and set the data source as the Tasks table
  • To add the automation, select the button and click on the Actions tab in the button properties panel
  • Configure your automation to delete the context row (aka the triggering row) or a specified row

Defining Honeycode resources

If you are using a managed policy you can skip this section. If you wish to restrict access at a more granular level, read on. The Honeycode resources that need to be defined in custom IAM policies for APIs are:

  • GetScreenData : screen
  • InvokeScreenAutomation : screen-automation

Screen format

The ARN format for a screen is:

arn:aws:honeycode:AWS Region:AWS account ID:screen:workbook/Workbook ID/app/App ID/screen/Screen ID

You can also use wildcards to specify parts of the ARN and include multiple resources underneath.To specify all screens in a single app you can use the following resource ARN:

arn:aws:honeycode:AWS Region:AWS account ID:screen:workbook/Workbook ID/app/App ID/screen/*

To specify all screens in all apps in a workbook, use the following resource ARN:

arn:aws:honeycode:AWS Region:AWS account ID:screen/Workbook ID/app/*


Screen automation format

The ARN format for a screen automation is:

arn:aws:honeycode:AWS Region:AWS account ID:screen-automation:workbook/Workbook ID/app/App ID/screen/Screen ID/automation/Automation ID

You can also use wildcards to specify parts of the ARN and include multiple resources underneath. To specify all automations in a specific screen, you can use the following resource ARN in your IAM policy:

arn:aws:honeycode:AWS Region:AWS account ID:screen-automation:workbook/Workbook ID/app/App ID/screen/Screen ID/automation/Automation ID/automation/

Similarly, to specify all automations in a single app you can use the following resource ARN in your IAM policy:

arn:aws:honeycode:AWS Region:AWS account ID:screen-automation:workbook/Workbook ID/app/App ID/screen/*

To specify all automations in all apps in a workbook, use the following resource ARN:

arn:aws:honeycode:AWS Region:AWS account ID:screen-automation:workbook/Workbook ID/app/*

Finally, to specify all automations in all workbooks in your account, you can either use the resource ARN "*" or an ARN in the following format:

arn:aws:honeycode:AWS Region:AWS account ID:screen-automation:workbook/*


GetScreenData API

This API allows you to retrieve data from a screen in a Honeycode app. You can set local variables in the screen to filter, sort, or otherwise affect what is displayed on the screen. This is a read-only API and will not affect data in your workbooks.

GetScreenData parameters

If you want to read a screen programmatically using the GetScreenData API, you will need:

Required:

  • Workbook ID
  • App ID
  • Screen ID
  • Any variables (used to set the value of the variable in the automation)

Optional:

  • Max results (default value is 100)
  • Next token (if the previous request specified a pagination token and you’d like to load the next page)

Syntax (AWS CLI):

aws honeycode get-screen-data \
  --profile <profile-name> \
  --workbook-id <workbook-id> \
  --app-id <app-id> \
  --screen-id <screen-id> \
  --max-results <max-results> \
  --next-token <next-token> \
  --variables <variables-json>

There is no reference to logged-in user when calling the GetScreenData API. Formulas with SYS_USER and personalization will not work.


InvokeScreenAutomation API

This API allows you to invoke an action defined in a screen in a Honeycode app, such as overwriting data, adding, or deleting a row of data. You can set local variables, which can then be used in the automation you’re invoking.

InvokeScreenAutomation parameters

Required:

  • Workbook ID
  • App ID
  • Screen ID
  • Screen automation ID
  • Client request token (it is used to reduce multiple requests in case of retries after transient timeouts)
  • Any variables (used to set the value of the variable in the automation)

Optional:

  • Row ID (needed only if the automation is specified inside a block with source)

Syntax (AWS CLI):

aws honeycode invoke-screen-automation \
  --profile <profile-name> \
  --workbook-id <workbook-id> \
  --app-id <app-id> \
  --screen-id <screen-id> \
  --screen-automation-id <screen-automation-id> \
  --client-request-token <client-request-token> \
  --row-id <row-id> \
  --variables <variables-json>

You can write only as many rows into Honeycode as your screen would at one time (e.g., no batched writes with arbitrary number of rows at once, but 1-n rows at a time based on how you have set up the screen).

As with GetScreenData , there is no notion of logged-in user. Using SYS_USER to write column values will not work. The InvokeScreenAutomation API only allows writing to variable data cells. The API cannot be used to write to shared data cells .


AWS CLI examples

At this stage, you’re all set to use Honeycode APIs. If you’ve already set up AWS CLI, this might be the easiest way to verify that everything is working. If you haven’t already set up the CLI, follow the guide.


Making a basic query

An example of a basic query to read a list of tasks using the GetScreenData API.

Request:

aws honeycode get-screen-data \
  --profile <my-auth-profile>\
  --workbook-id <workbook-id> \
  --app-id <app-id> \
  --screen-id <screen-id> \
  --max-results 2

Response:
It loads the first two tasks from the Tasks table. Since there are more than two rows that match the list formula, nextToken is included in the response to continue loading data in subsequent calls.

{
  "nextToken": "<<Next Token Value>>",
  "results": {
    "Tasks List": {
      "headers": [
        {
          "format": "Text",
          "name": "Task"
        },
        {
          "format": "Text",
          "name": "Status"
        }
      ],
      "rows": [
        {
          "dataItems": [
            {
              "formattedValue": "Try Honeycode",
              "rawValue": "Try Honeycode"
            },
            {
              "formattedValue": "In Progress",
              "rawValue": "In Progress"
            }
          ],
          "tableRowId": "<<A Row ID is here>>"
        },
        {
          "dataItems": [
            {
              "formattedValue": "Create a new app in Honeycode",
              "rawValue": "Create a new app in Honeycode"
            },
            {
              "formattedValue": "Not Started",
              "rawValue": "Not Started"
            }
          ],
          "tableRowId": "<<A Row ID is here>>"
        }
      ]
    }
  },
  "workbookCursor": <<A number is here>>
}

Note the format field in the header for rows where the format is set on the formulas on the screen.


Using next token

This GetScreenData example takes the pagination token from the previous response and includes it in the input JSON file for the next call. Remaining parameters are the same as in previous request.

Note that nextToken is different for different calls, even with the same set of parameters. The token expires after one hour, so if you paste the request below, you’ll l get an error response that the token is expired. You’ll need to run the previous request and copy the token from the output into this request.

Request:

aws honeycode get-screen-data \
  --profile <my-auth-profile> \
  --workbook-id <workbook-id> \
  --app-id <app-id> \
  --screen-id <screen-id> \
  --max-results 2' \
  --next-token <Next Token Value>

Response:
Includes data for the next two tasks. If there are more results matching the query, a new pagination token is included in the response.

{
  "nextToken": "<<Next Token Value>>",
  "results": {
    "Tasks List": {
        "headers": [
        {
          "format": "Text",
          "name": "Task"
        },
        {
          "format": "Text",
          "name": "Status"
        }
      ],
      "rows": [
        {
          "dataItems": [
            {
              "formattedValue": "Try API in Honeycode",
              "rawValue": "Try API in Honeycode"
            },
            {
              "formattedValue": "Not Started",
              "rawValue": "Not Started"
            }
          ],
          "tableRowId": "<<A Row ID is here>>"
        },
        {
          "dataItems": [
            {
              "formattedValue": "Read a book",
              "rawValue": "Read a book"
            },
            {
              "formattedValue": "Not Started",
              "rawValue": "Not Started"
            }
          ],
          "tableRowId": "<<A Row Id is here>>"
        }
      ]
    }
  },
  "workbookCursor": <<A number is here>>
}

Passing named variables

This GetScreenData example loads the the list used in the previous example, filtered by the status “Not Started.”

Request:

aws honeycode get-screen-data \
  --profile <my-auth-profile>\
  --workbook-id <workbook-id> \
  --app-id <app-id> \
  --screen-id <screen-id> \
  --max-results 2 \
  --variables '{"Status Filter": { "rawValue": "Not Started"}}'

Response:
Includes data for the for all the tasks that match the specified status. If there are more results matching the query, a new pagination token is included in the response.

{
  "nextToken": "<<Next Token Value>>",
  "results": {
    "Tasks List": {
        "headers": [
        {
          "format": "Text",
          "name": "Task"
        },
        {
          "format": "Text",
          "name": "Status"
        }
      ],
      "rows": [
         {
          "dataItems": [
            {
              "formattedValue": "Create a new app in Honeycode",
              "rawValue": "Create a new app in Honeycode"
            },
            {
              "formattedValue": "Not Started",
              "rawValue": "Not Started"
            }
          ],
          "tableRowId": "<<A Row ID is here>>"
        },
        {
          "dataItems": [
            {
              "formattedValue": "Try API in Honeycode",
              "rawValue": "Try API in Honeycode"
            },
            {
              "formattedValue": "Not Started",
              "rawValue": "Not Started"
            }
          ],
          "tableRowId": "<<A Row ID is here>>"
        },
        {
          "dataItems": [
            {
              "formattedValue": "Read a book",
              "rawValue": "Read a book"
            },
            {
              "formattedValue": "Not Started",
              "rawValue": "Not Started"
            }
          ],
          "tableRowId": "<<A Row ID is here>>"
        }
      ]
    }
  },
  "workbookCursor": <<A number is here>>
}

Adding a row

This InvokeScreenAutomation example adds a new row with the values “Test” and “Not Started” in the Tasks table.

The variables field of the InvokeScreenAutomation request is an optional field. It is used to set the value of the variable used in the automation. It is a map with the variable name as the map key and the value to set as the map value. In the example below, the variables used in the automation are $[Task] and $[Status] .

{
    "Task": {
      "rawValue": "Test"
    },
    "Status": {
      "rawValue": "Not Started"
    }
}

Request :

aws honeycode invoke-screen-automation \
  --profile <my-auth-profile> \
  --workbook-id <workbook-id> \
  --app-id <app-id> \
  --screen-id <screen-id> \
  --screen-automation-id <screen-automation-id> \
  --client-request-token <client-request-token> \
  --variables '{"Task": {"rawValue": "Test"}, "Status":{"rawValue": "Not Started"}}'

Response:
A new task with the name “Test” is added to the Tasks table.

Overwriting a row

In this InvokeScreenAutomation example, the variables used in the automation are $[Row] , $[Task] and $[Status] . The table row ID for the variable $[Row] is located in the output of the GetScreenData calls.

{
    "Row": {
      "rawValue": "<<Table row ID goes here>>"
    },
    "Task": {
      "rawValue": "Test"
    },
    "Status": {
      "rawValue": "In Progress"
    }
}

Request :

aws honeycode invoke-screen-automation \
 --profile <my-auth-profile> \
 --workbook-id <workbook-id> \
 --app-id <app-id> \
 --screen-id <screen-id> \
 --screen-automation-id <screen-automation-id> \
 --client-request-token <client-request-token> \
 --variables '{"variables": {"Row": {"rawValue": "<<Table row ID goes here>>"}, "Task": {"rawValue": "Test"}, "Status":{"rawValue": "In Progress"}}'

Response:
The status of the “Test” task is updated .


Deleting a row

In this example, the variable used in the automation is $[Row] . The table row ID for the variable $[Row] is be located in the output of the GetScreenData calls. A sample call might look like:

{
    "Row": {
      "rawValue": "<<Table row ID goes here>>"
    }
}

Request:

aws honeycode invoke-screen-automation \
  --profile <my-auth-profile> \
  --workbook-id <workbook-id> \
  --app-id <app-id> \
  --screen-id <screen-id> \
  --screen-automation-id <screen-automation-id> \
  --client-request-token <client-request-token> \
  --variables '{"Row": {"rawValue": "<<Table row ID goes here>>"}}'

Response:
The “Test” task is deleted.


Python SDK examples

In this section, we will make the same calls as above using Python script with the AWS SDK. If you haven't installed the SDK already,follow the guide (https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html).

You can use the code snippet below to set up a client. Here, we're using a profile to set up the session, but you can choose to do it in other ways.

import boto3
import json

session = boto3.Session(profile_name = 'sample-honeycode-profile')
honeycode_client = session.client('honeycode', region_name = 'us-west-2')

Making a basic query

An example of a basic query to read a list of tasks using the GetScreenData API. The following code snippet can be used to make a call to get rows from the Tasks table.

Request:

response = honeycode_client.get_screen_data(
    workbookId = '<workbookId>',
    appId = '<appId>',
    screenId = '<screenId>',
    maxResults = 2)
print(json.dumps(response, indent = 4))

Note that we set maxResults to 2 to demonstrate pagination. The default is 100, and its inclusion is optional.

Output:

{
  "ResponseMetadata": {
    "RequestId": "<<RequestId is here>>",
    "HTTPStatusCode": 200,
    "HTTPHeaders": {
      "content-type": "application/json",
      "content-length": "1295",
      "connection": "keep-alive",
      "date": "Tue, 05 May 2020 22:01:41 GMT",
      "x-amzn-requestid": "<<RequestId is here>>",
      "x-amzn-remapped-x-amzn-requestid": "<<RequestId is here>>",
      "x-amzn-remapped-content-length": "1295",
      "x-amz-apigw-id": "MFBK0F3WPHcFcCg=",
      "x-amzn-trace-id": "<<TraceId is here>>",
      "x-amzn-remapped-date": "<<Timestamp here>>",
    },
    "RetryAttempts": 0
  },
  "results": {
  "nextToken": "<<Next Token Value>>",
  "results": {
    "Tasks List": {
        "headers": [
        {
          "format": "Text",
          "name": "Task"
        },
        {
          "format": "Text",
          "name": "Status"
        }
      ],
      "rows": [
        {
          "dataItems": [
            {
              "formattedValue": "Try API in Honeycode",
              "rawValue": "Try API in Honeycode"
            },
            {
              "formattedValue": "Not Started",
              "rawValue": "Not Started"
            }
          ],
          "tableRowId": "<<A Row ID is here>>"
        },
        {
          "dataItems": [
            {
              "formattedValue": "Read a book",
              "rawValue": "Read a book"
            },
            {
              "formattedValue": "Not Started",
              "rawValue": "Not Started"
            }
          ],
          "tableRowId": "<<A Row Id is here>>"
        }
      ]
    }
  },
  "workbookCursor": <<A number is here>>,
  "nextToken": "<< Token string is here>>"
}

Using next token

This GetScreenData example takes the pagination token from the previous response and includes it in the input JSON file for the next call. Remaining parameters are the same as in previous request.

Note that nextToken is different for different calls, even with the same set of parameters. The token expires after one hour, so if you paste the request below, you’ll l get an error response that the token is expired. You’ll need to run the previous request and copy the token from the output into this request.

response = honeycode_client.get_screen_data(
    workbookId = '<workbook-id>',
    appId = '<app-id>',
    screenId = '<screen-id>',
    maxResults = 2)

next_token = response['nextToken']

response = honeycode_client.get_screen_data(
    workbookId = '<workbook-id>',
    appId = '<app-id>',
    screenId = '<screen-id>',
    maxResults = 2,
    nextToken = next_token)
print(json.dumps(response, indent = 2))

Passing named variables

Request:
This GetScreenData example filters the Tasks table to display only tasks that are with the status “Not Started.”

response = honeycode_client.get_screen_data(
    workbookId = '<workbook-id>',
    appId = '<app-id>',
    screenId = '<screen-id>',
    variables = {"Status Filter": { "rawValue": "Not Started"}})
print(json.dumps(response, indent = 2))

Add a row

This InvokeScreenAutomation example shows how to add rows in a Tasks table.

honeycode_client.invoke_screen_automation(
    workbookId = '<workbook-id>',
    appId = '<app-id>',
    screenId = '<create-row-screen-id>',
    screenAutomationId = ' <screen-automation-id>',
    variables = {"Task": {"rawValue": "Test"}, "Status":{"rawValue": "Not Started"}})
    rowId = <same rowId being used for row variable>

Overwrite a row

This InvokeScreenAutomation example shows how to overwrite rows in a Tasks table.

honeycode_client.invoke_screen_automation(
    workbookId = '<workbook-id>',
    appId = '<app-id>',
    screenId = '<update-row-screen-id>',
    screenAutomationId = ' <screen-automation-id>',
    variables = {"Row": {"rawValue": "<<Table row ID goes here>>"}, "Task": {"rawValue": "Test"}, "Status":{"rawValue": "In Progress"}})

Delete a row

This InvokeScreenAutomation example shows how to delete rows in a Tasks table.

honeycode_client.invoke_screen_automation(
    workbookId = '<workbook-id>',
    appId = '<app-id>',
    screenId = '<delete-row-screen-id>',
    screenAutomationId = ' <screen-automation-id>',
    variables = {"Row": {"rawValue": "<<Table row ID goes here>>"}})

Table metadata APIs

This section describes the data model for the following table metadata APIs:

  • ListTables
  • ListTableColumns

Setting up for table metadata APIs

For these APIs, you’ll need to first create a table and add some data.

Create a table

If you haven’t already done so, create a new workbook and add a new table either by importing a CSV file or by adding data manually. In the example below, we start with a simple table that tracks stock prices.

Table Metadata Image

Define Honeycode resources

If you are using a managed policy you can skip this section. If you wish to restrict access at a more granular level, read on. The Honeycode resources that need to be defined in custom IAM policies for metadata APIs are:

  • ListTables: workbook
  • ListTableColumns: table

Workbook ARN format

The ARN format for a workbook is:

arn:aws:honeycode:AWS Region:AWS account ID:workbook:workbook/Workbook ID

:hammer_and_wrench: Builder tip: You will need an app to get the workbook ARN. Simply right-click on any app object in builder to access the ARN and IDs modal. If you don't have a use case for an app, you can use the App Wizard to quickly create a simple app to grab the Workbook ID and then delete the app as necessary.

You can also use wildcards to specify parts of the ARN and include multiple resources. To specify all workbooks you can use the following resource ARN:

arn:aws:honeycode:AWS Region:AWS account ID:workbook:workbook/*

Table ARN format

The ARN format for a table is:

arn:aws:honeycode:AWS Region:AWS account ID:table:workbook/Workbook ID/table/Table ID

You can also use wildcards to specify parts of the ARN and include multiple resources underneath. To specify all tables in a single workbook you can use the following resource ARN:

arn:aws:honeycode:AWS Region:AWS account ID:table:workbook/Workbook ID/table/*

To specify all tables in all workbooks, use the following resource ARN:

arn:aws:honeycode:AWS Region:AWS account ID:table:workbook/*/table/*


ListTables API

List all tables in a workbook. Replace with your workbook id.

AWS CLI example

aws honeycode list-tables \
  --workbook-id "<workboook-id>"

Python SDK example

response = honeycode_client.list_tables(
    workbookId = '<workbook-id>')

Response

{
    "tables": [
        {
            "tableId": "<table-id>",
            "tableName": "Stocks"
        }
    ],
    "workbookCursor": 1273158992
}

ListTableColumns API

List all columns in a table. Replace with your workbook id and with the table id from the ListTables response.

AWS CLI example

aws honeycode list-table-columns \
  --workbook-id "<workboook-id>" \
  --table-id "<table-id>"

Python SDK example

response = honeycode_client.list_table_columns(
    workbookId = '<workbook-id>',
    tableId = '<table-id>')

Response

{
    "tableColumns": [
        {
            "format": "AUTO",
            "tableColumnId": "<symbol-column-id>",
            "tableColumnName": "Symbol"
        },
        {
            "format": "CURRENCY",
            "tableColumnId": "<price-column-id>",
            "tableColumnName": "Price"
        },
        {
            "format": "CURRENCY",
            "tableColumnId": "<previous-price-column-id>",
            "tableColumnName": "Previous Price"
        },
        {
            "format": "PERCENTAGE",
            "tableColumnId": "<percentage-change-column-id>",
            "tableColumnName": "Change"
        },
        {
            "format": "DATE_TIME",
            "tableColumnId": "<last-update-column-id>",
            "tableColumnName": "Last Update"
        }
    ],
    "workbookCursor": 1288302476
}

Table row operations APIs

The Table Row Operations APIs are useful when wanting to connect your Honeycode tables with external sources. There are several things that you can do:

Create or add new rows to a table.
Read or retrieve rows from a table.
Update or edit rows in a table.
Delete or remove rows from a table.

This section is describes the data models for the following APIs:

  • BatchCreateTableRows
  • BatchDeleteTableRows
  • BatchUpdateTableRows
  • BatchUpsertTableRows
  • ListTableRows
  • QueryTableRows

Setting up for table row operations APIs

If you haven’t already done so, create a new workbook and add a new table either by importing a CSV file or by adding data manually. In the example below, we start with a simple table that tracks stock prices, similar to the table metadata APIs.

Table row operations Image

Defining Honeycode resources

If you are using a managed policy you can skip this section. If you wish to restrict access at a more granular level, read on. The Honeycode resources that need to be defined in custom IAM policies for table row operations APIs are:

  • ListTableRows: table
  • QueryTableRows: table
  • BatchCreateTableRows: table
  • BatchUpdateTableRows: table
  • BatchUpsertTableRows: table
  • BatchDeleteTableRows: table

Table ARN format

The ARN format for a table is:

arn:aws:honeycode:AWS Region:AWS account ID:table:workbook/Workbook ID/table/Table ID

You can also use wildcards to specify parts of the ARN and include multiple resources underneath. To specify all tables in a single workbook you can use the following resource ARN:

arn:aws:honeycode:AWS Region:AWS account ID:table:workbook/Workbook ID/table/*

To specify all tables in all workbooks, use the following resource ARN:

arn:aws:honeycode:AWS Region:AWS account ID:table:workbook/*/table/*


ListTableRows API

List all the rows in a table. Replace with your workbook id and with the table id from the ListTables response. Note that maxResults is set to 3 to show how pagination works.

AWS CLI example

aws honeycode list-table-rows \
  --workbook-id "<workboook-id>" \
  --table-id "<table-id>" \
  --max-results 3

Python SDK example

response = honeycode_client.list_table_rows(
    workbookId = '<workbook-id>',
    tableId = '<table-id>',
    maxResults = 3)

Response

{
    "columnIds": [
        "<symbol-column-id>",
        "<price-column-id>",
        "<previous-price-column-id>",
        "<percentage-change-column-id>",
        "<last-update-column-id>"
    ],
    "nextToken": "<token-for-page-2>",
    "rows": [
        {
            "cells": [
                {
                    "format": "AUTO",
                    "formattedValue": "AMZN",
                    "rawValue": "AMZN"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$3,241.16",
                    "rawValue": "3241.16"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$3,048.41",
                    "rawValue": "3048.41"
                },
                {
                    "format": "PERCENTAGE",
                    "formattedValue": "6.32%",
                    "formula": "=[Price]/[Previous Price]-1",
                    "rawValue": "0.06322968367116"
                },
                {
                    "format": "DATE_TIME",
                    "formattedValue": "11/4/20 6:00 PM",
                    "rawValue": "44139.75"
                }
            ],
            "rowId": "<amzn-row-id>"
        },
        {
            "cells": [
                {
                    "format": "AUTO",
                    "formattedValue": "AAPL",
                    "rawValue": "AAPL"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$114.95",
                    "rawValue": "114.95"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$110.44",
                    "rawValue": "110.44"
                },
                {
                    "format": "PERCENTAGE",
                    "formattedValue": "4.08%",
                    "formula": "=[Price]/[Previous Price]-1",
                    "rawValue": "0.040836653386454"
                },
                {
                    "format": "DATE_TIME",
                    "formattedValue": "11/4/20 6:00 PM",
                    "rawValue": "44139.75"
                }
            ],
            "rowId": "<aapl-row-id>"
        },
        {
            "cells": [
                {
                    "format": "AUTO",
                    "formattedValue": "FB",
                    "rawValue": "FB"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$287.38",
                    "rawValue": "287.38"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$265.30",
                    "rawValue": "265.3"
                },
                {
                    "format": "PERCENTAGE",
                    "formattedValue": "8.32%",
                    "formula": "=[Price]/[Previous Price]-1",
                    "rawValue": "0.083226535996985"
                },
                {
                    "format": "DATE_TIME",
                    "formattedValue": "11/4/20 6:00 PM",
                    "rawValue": "44139.75"
                }
            ],
            "rowId": "<fb-row-id>"
        }
    ],
    "workbookCursor": 1288302476
}

Note that the nextToken in the response indicates that there is more data to load. You can pass that value as the nextToken parameter in a subsequent request to retrieve page 2. The new response has no nextToken since all 6 rows in the table have been loaded.

AWS CLI example (nextToken)

aws honeycode list-table-rows \
  --workbook-id "<workboook-id>" \
  --table-id "<table-id>" \
  --max-results 3 \
  --next-token "<token-for-page-2>"

Python SDK example (nextToken)

response = honeycode_client.list_table_rows(
    workbookId = '<workbook-id>',
    tableId = '<table-id>',
    maxResults = 3,
    nextToken = '<token-for-page-2>')

Response (nextToken)

{
    "columnIds": [
        "<symbol-column-id>",
        "<price-column-id>",
        "<previous-price-column-id>",
        "<percentage-change-column-id>",
        "<last-update-column-id>"
    ],
    "rows": [
        {
            "cells": [
                {
                    "format": "AUTO",
                    "formattedValue": "GOOG",
                    "rawValue": "GOOG"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$1,749.13",
                    "rawValue": "1749.13"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$1,650.21",
                    "rawValue": "1650.21"
                },
                {
                    "format": "PERCENTAGE",
                    "formattedValue": "5.99%",
                    "formula": "=[Price]/[Previous Price]-1",
                    "rawValue": "0.05994388592967"
                },
                {
                    "format": "DATE_TIME",
                    "formattedValue": "11/4/20 6:00 PM",
                    "rawValue": "44139.75"
                }
            ],
            "rowId": "<goog-row-id>"
        },
        {
            "cells": [
                {
                    "format": "AUTO",
                    "formattedValue": "NFLX",
                    "rawValue": "NFLX"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$496.95",
                    "rawValue": "496.95"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$487.22",
                    "rawValue": "487.22"
                },
                {
                    "format": "PERCENTAGE",
                    "formattedValue": "2.00%",
                    "formula": "=[Price]/[Previous Price]-1",
                    "rawValue": "0.019970444563031"
                },
                {
                    "format": "DATE_TIME",
                    "formattedValue": "11/4/20 6:00 PM",
                    "rawValue": "44139.75"
                }
            ],
            "rowId": "<nflx-row-id>"
        },
        {
            "cells": [
                {
                    "format": "AUTO",
                    "formattedValue": "MSFT",
                    "rawValue": "MSFT"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$216.39",
                    "rawValue": "216.39"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$206.43",
                    "rawValue": "206.43"
                },
                {
                    "format": "PERCENTAGE",
                    "formattedValue": "4.82%",
                    "formula": "=[Price]/[Previous Price]-1",
                    "rawValue": "0.04824880104636"
                },
                {
                    "format": "DATE_TIME",
                    "formattedValue": "11/4/20 6:00 PM",
                    "rawValue": "44139.75"
                }
            ],
            "rowId": "<msft-row-id>"
        }
    ],
    "workbookCursor": 1288302476
}

ListTableRows API can also be called with specific row ids in the input. In this case, the API returns only the requested row ids.

AWS CLI example (row IDs)

aws honeycode list-table-rows \
  --workbook-id "<workboook-id>" \
  --table-id "<table-id>" \
  --row-ids '["<amzn-row-id>", "<msft-row-id>"]'

Python SDK Example (row IDs)

response = honeycode_client.list_table_rows(
    workbookId = '<workbook-id>',
    tableId = '<table-id>',
    rowIds = ['<amzn-row-id>', '<msft-row-id>'])

Response (row IDs)

{
    "columnIds": [
        "<symbol-column-id>",
        "<price-column-id>",
        "<previous-price-column-id>",
        "<percentage-change-column-id>",
        "<last-update-column-id>"
    ],
    "rowIdsNotFound": [],
    "rows": [
        {
            "cells": [
                {
                    "format": "AUTO",
                    "formattedValue": "AMZN",
                    "rawValue": "AMZN"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$3,241.16",
                    "rawValue": "3241.16"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$3,048.41",
                    "rawValue": "3048.41"
                },
                {
                    "format": "PERCENTAGE",
                    "formattedValue": "6.32%",
                    "formula": "=[Price]/[Previous Price]-1",
                    "rawValue": "0.06322968367116"
                },
                {
                    "format": "DATE_TIME",
                    "formattedValue": "11/4/20 6:00 PM",
                    "rawValue": "44139.75"
                }
            ],
            "rowId": "<amzn-row-id>"
        },
        {
            "cells": [
                {
                    "format": "AUTO",
                    "formattedValue": "MSFT",
                    "rawValue": "MSFT"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$216.39",
                    "rawValue": "216.39"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$206.43",
                    "rawValue": "206.43"
                },
                {
                    "format": "PERCENTAGE",
                    "formattedValue": "4.82%",
                    "formula": "=[Price]/[Previous Price]-1",
                    "rawValue": "0.04824880104636"
                },
                {
                    "format": "DATE_TIME",
                    "formattedValue": "11/4/20 6:00 PM",
                    "rawValue": "44139.75"
                }
            ],
            "rowId": "<msft-row-id>"
        }
    ],
    "workbookCursor": 1288302476
}

QueryTableRows API

This API can be used to query for specific rows in the table using a filter function. The following example finds all stocks that had more than 6.00% change from the previous price.

AWS CLI example

aws honeycode query-table-rows \
  --workbook-id "<workboook-id>" \
  --table-id "<table-id>" \
  --filter-formula '{"formula": "=Filter(Stocks,\"Stocks[Change]>0.06\")"}'

Python SDK example

response = honeycode_client.query_table_rows(
    workbookId = '<workbook-id>',
    tableId = '<table-id>',
    filterFormula = { "formula": "=Filter(Stocks,\"Stocks[Change]>0.06\")"} )

Response

{
    "columnIds": [
        "<symbol-column-id>",
        "<price-column-id>",
        "<previous-price-column-id>",
        "<percentage-change-column-id>",
        "<last-update-column-id>"
    ],
    "rows": [
        {
            "cells": [
                {
                    "format": "AUTO",
                    "formattedValue": "AMZN",
                    "rawValue": "AMZN"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$3,241.16",
                    "rawValue": "3241.16"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$3,048.41",
                    "rawValue": "3048.41"
                },
                {
                    "format": "PERCENTAGE",
                    "formattedValue": "6.32%",
                    "formula": "=[Price]/[Previous Price]-1",
                    "rawValue": "0.06322968367116"
                },
                {
                    "format": "DATE_TIME",
                    "formattedValue": "11/4/20 6:00 PM",
                    "rawValue": "44139.75"
                }
            ],
            "rowId": "<amzn-row-id>"
        },
        {
            "cells": [
                {
                    "format": "AUTO",
                    "formattedValue": "FB",
                    "rawValue": "FB"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$287.38",
                    "rawValue": "287.38"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$265.30",
                    "rawValue": "265.3"
                },
                {
                    "format": "PERCENTAGE",
                    "formattedValue": "8.32%",
                    "formula": "=[Price]/[Previous Price]-1",
                    "rawValue": "0.083226535996985"
                },
                {
                    "format": "DATE_TIME",
                    "formattedValue": "11/4/20 6:00 PM",
                    "rawValue": "44139.75"
                }
            ],
            "rowId": "<fb-row-id>"
        }
    ],
    "workbookCursor": 1288302476
}

Python SDK Example using f-string

amzn_stock = 'AMZN'
response = honeycode_client.query_table_rows(
    workbookId = '<workbook-id>',
    tableId = '<table-id>',
    filterFormula = { "formula": f'=Filter(Stocks,"Stocks[Symbol]=%", "{amzn_stock}")'} )

Response

{
    "columnIds": [
        "<symbol-column-id>",
        "<price-column-id>",
        "<previous-price-column-id>",
        "<percentage-change-column-id>",
        "<last-update-column-id>"
    ],
    "rows": [
        {
            "cells": [
                {
                    "format": "AUTO",
                    "formattedValue": "AMZN",
                    "rawValue": "AMZN"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$3,241.16",
                    "rawValue": "3241.16"
                },
                {
                    "format": "CURRENCY",
                    "formattedValue": "$3,048.41",
                    "rawValue": "3048.41"
                },
                {
                    "format": "PERCENTAGE",
                    "formattedValue": "6.32%",
                    "formula": "=[Price]/[Previous Price]-1",
                    "rawValue": "0.06322968367116"
                },
                {
                    "format": "DATE_TIME",
                    "formattedValue": "11/4/20 6:00 PM",
                    "rawValue": "44139.75"
                }
            ],
            "rowId": "<amzn-row-id>"
        }
    ],
    "workbookCursor": 1288302476
}

BatchCreateTableRows API

This API can be used to append a batch of rows to the end of a table. The following example demonstrates using BatchCreateTableRows API to add two rows at the end of a table.

Note:

  1. This API takes a BatchItemID in the input. This is an identifier that you can assign to that particular row so that you can link the row id in the response with the item in the request.
  2. The cellsToCreate map needs the ids of the columns in the table. You can get these ids from the ListTableColumns API.
  3. The column Change has a column level formula. So it does not need to be included in the input as the column formula will be automatically applied to the new rows. You can include the column in the input if you want to override the column formula for the new rows with a different value.

AWS CLI example

aws honeycode batch-create-table-rows \
  --workbook-id "<workboook-id>" \
  --table-id "<table-id>" \
  --rows-to-create '[ 
    {
      "batchItemId": "item-001",
      "cellsToCreate": {
        "<symbol-column-id>": { "fact": "AAA" },
        "<price-column-id>": { "fact": "23.47" },
        "<previous-price-column-id>": { "fact": "27.27" },
        "<last-updated-column-id>": { "fact": "11/5/20 6:00 PM" }
      }
    },
    {
      "batchItemId": "item-002",
      "cellsToCreate": {
        "<symbol-column-id>": { "fact": "BBB" },
        "<price-column-id>": { "fact": "108" },
        "<previous-price-column-id>": { "fact": "127.2" },
        "<last-updated-column-id>": { "fact": "11/5/20 6:00 PM" }
      }
    }
]'

Python SDK example

def create_row_data(batch_item_id, symbol, price, previous_price, last_updated):
  return {
    "batchItemId": batch_item_id,
    "cellsToCreate": {
      "<symbol-column-id>": { "fact": symbol },
      "<price-column-id>": { "fact": price },
      "<previous-price-column-id>": { "fact": previous_price},
      "<last-updated-column-id>": { "fact": last_updated }
    }
  }

response = honeycode_client.batch_create_table_rows(
    workbookId = '<workbook-id>',
    tableId = '<table-id>',
    rowsToCreate = [
        create_row_data("item-001", "AAA", "23.47", "27.27", "11/5/20 6:00 PM"),
        create_row_data("item-002", "BBB", "108", "127.2", "11/5/20 6:00 PM")
    ])

Response

{
    "createdRows": {
        "item-001": "<aaa-row-id>",
        "item-002": "<bbb-row-id>"
    },
    "workbookCursor": 1288497196
}

After the rows are inserted, this is how the table looks:

BatchCreateTableRows API


BatchUpdateTableRows API

This API can be used to update the data in one or more columns of specific rows in a table. The following example demonstrates updating the price column of one row and the date column of another row in the same request.

AWS CLI example

aws honeycode batch-update-table-rows \
  --workbook-id "<workboook-id>" \
  --table-id "<table-id>" \
  --rows-to-update '[ 
    {
      "rowId": "<aaa-row-id>",
      "cellsToUpdate": {
        "<price-column-id>": { "fact": "24.74" }
      }
    },
    {
      "rowId": "<bbb-row-id>",
      "cellsToUpdate": {
        "<last-updated-column-id>": { "fact": "11/7 5:59 PM" }
      }
    }
]'

Python SDK example

response = honeycode_client.batch_update_table_rows(
    workbookId = '<workbook-id>',
    tableId = '<table-id>',
    rowsToUpdate = [
        {
          "rowId": "<aaa-row-id>",
          "cellsToUpdate": {
            "<price-column-id>": { "fact": "24.74" }
          }
        },
        {
          "rowId": "<bbb-row-id>",
          "cellsToUpdate": {
            "<last-updated-column-id>": { "fact": "11/7 5:59 PM" }
          }
        }
    ])

Response

{
    "workbookCursor": 1288538679
}

After the rows are updated, this is how the table looks:

Batch Update Image


BatchUpsertTableRows API

This API will upsert one or more rows in a table. The upsert operation takes a filter formula as input and uses it to find matching rows in the table. If matching rows are found, cells in those rows are updated as specified in the request. If a matching row is not found, a new row is created and cells in the new row are set as specified in the request.

The following example shows this API being called with two batch items. One batch item finds an existing row and updates it and the second batch item creates a new row.

AWS CLI example

aws honeycode batch-upsert-table-rows \
  --workbook-id "<workboook-id>" \
  --table-id "<table-id>" \
  --rows-to-upsert '[ 
    {
      "batchItemId": "item-001",
      "filter": { "formula": "=Filter(Stocks,\"Stocks[Symbol]=%\",\"BBB\")" },
      "cellsToUpdate": {
        "<symbol-column-id>": { "fact": "BBB" },
        "<price-column-id>": { "fact": "25.32" },
        "<previous-price-column-id>": { "fact": "28.76" },
        "<last-updated-column-id>": { "fact": "11/8 6:13 PM" }
      }
    },
    {
      "batchItemId": "item-002",
      "filter": { "formula": "=Filter(Stocks,\"Stocks[Symbol]=%\",\"CCC\")" },
      "cellsToUpdate": {
        "<symbol-column-id>": { "fact": "CCC" },
        "<price-column-id>": { "fact": "110.8" },
        "<previous-price-column-id>": { "fact": "108.10" },
        "<last-updated-column-id>": { "fact": "11/8 6:13 PM" }
      }
    }
]'

Python SDK example

def upsert_row_data(batch_item_id, filter_formula, symbol, price, previous_price, last_updated):
  return {
    "batchItemId": batch_item_id,
    "filter": { "formula": filter_formula },
    "cellsToUpdate": {
      "<symbol-column-id>": { "fact": symbol },
      "<price-column-id>": { "fact": price },
      "<previous-price-column-id>": { "fact": previous_price},
      "<last-updated-column-id>": { "fact": last_updated }
    }
  }

response = honeycode_client.batch_upsert_table_rows(
    workbookId = '<workbook-id>',
    tableId = '<table-id>',
    rowsToUpsert = [
        upsert_row_data("item-001", "=Filter(Stocks,\"Stocks[Symbol]=%\",\"BBB\")", "BBB", "25.32", "28.76", "11/8 6:13 PM"),
        upsert_row_data("item-002", "=Filter(Stocks,\"Stocks[Symbol]=%\",\"CCC\")", "CCC", "110.8", "108.10", "11/8 6:13 PM")
    ])

Response

{
    "rows": {
        "item-001": {
            "rowIds": [ "<bbb-row-id>" ],
            "upsertAction": "UPDATED"
        },
        "item-002": {
            "rowIds": [ "<ccc-row-id>" ],
            "upsertAction": "APPENDED"
        }
    },
    "workbookCursor": 1288566784
}

After the rows are upserted, this is how the table looks.

Batch Upsert Image

BatchDeleteTableRows API

This API will delete the list of rows passed in the input. The following example illustrates this by deleting the rows with stock symbols AAA , BBB and CCC using their row ids.

AWS CLI example

aws honeycode batch-delete-table-rows \
  --workbook-id "<workboook-id>" \
  --table-id "<table-id>" \
  --rowIds '["<aaa-row-id>", "<bbb-row-id">, "<ccc-row-id>"]'

Python SDK example

response = honeycode_client.batch_delete_table_rows(
  workbookId = '<workbook-id>',
  tableId = '<table-id>',
  rowIds = [ "<aaa-row-id>", "<bbb-row-id">, "<ccc-row-id>" ])

Response

{
   "workbookCursor": 1288604696
}

After the rows are deleted, this is how the table looks.

Batch Delete Image


ImportData APIs

This section describes the Import Data APIs:

  • StartTableDataImportJob API
    *DescribeTableDataImportJob API

Setting up for Table Data Import APIs

Defining Honeycode resources

If you are using a managed policy you can skip this section. If you wish to restrict access at a more granular level, read on. The Honeycode resources that need to be defined in custom IAM policies for import APIs are:

  • StartTableDataImportJob: table
  • DescribeTableDataImportJob: table

Table ARN format

The ARN format for a table is:

arn:aws:honeycode:AWS Region:AWS account ID:table:workbook/Workbook ID/table/Table ID

You can also use wildcards to specify parts of the ARN and include multiple resources underneath. To specify all tables in a single workbook you can use the following resource ARN:

arn:aws:honeycode:AWS Region:AWS account ID:table:workbook/Workbook ID/table/*

To specify all tables in all workbooks, use the following resource ARN:

arn:aws:honeycode:AWS Region:AWS account ID:table:workbook/*/table/*

StartTableDataImportJob API

The StartTableDataImportJob API starts a table data import job that runs in the background. Once the job is started, you can use the DescribeTableDataImportJob API to find the status of the import.

The following example shows how to import a CSV file to the Stocks table. First, create a CSV file with contents as follows:

Symbol,Price,Previous Price,Last Update
AAA,123.17,182.21,11/9/20 6:23 PM
BBB,127.27,128.13,11/9/20 6:23 PM

Upload this CSV to an S3 bucket. Use the following AWS CLI command to generate a presigned URL for the CSV. Be sure to replace with the S3 bucket name and with the name of the file you uploaded.

aws s3 presign s3://<bucket-name>/<file-name>

Copy the presigned URL from the output. This URL will need to be passed in as a parameter in the call to StartTableDataImportJob API.

Now the file is ready for import.

AWS CLI example

aws honeycode start-table-data-import-job \
  --workbook-id '<workbook-id>' \
  --table-id '<table-id>' \
  --dataSource '{ "dataSourceConfig": {"dataSourceUrl": "<presigned-url>" } }' \
  --dataFormat 'DELIMITED_TEXT' \
  --import-options '{
    "destinationOptions": {
      "columnMap": {
        "<symbol-column-id>": { "columnIndex": 1 },
        "<price-column-id>": { "columnIndex": 2 },
        "<previous-price-column-id>": { "columnIndex": 3 },
        "<last-update-column-id>": { "columnIndex": 4 }
      }
    },
    "delimitedTextOptions": {
      "delimiter": ",",
      "hasHeaderRow": true,
      "ignoreEmptyRow": true,
      "dataCharacterEncoding": "UTF-8"
    }
}' \
--client-request-token '<request-token>'

Python SDK example

response = honeycode_client.start_table_data_import_job(
    workbookId = '<workbook-id>',
    tableId = '<table-id>',
    dataSource = { "dataSourceConfig": {"dataSourceUrl": "<presigned-url>" } },
    dataFormat = 'DELIMITED_TEXT',
    importOptions = {
      "destinationOptions": {
        "columnMap": {
          "<symbol-column-id>": { "columnIndex": 1 },
          "<price-column-id>": { "columnIndex": 2 },
          "<previous-price-column-id>": { "columnIndex": 3 },
          "<last-update-column-id>": { "columnIndex": 4 }
        }
      },
      "delimitedTextOptions": {
        "delimiter": ",",
        "hasHeaderRow": true,
        "ignoreEmptyRow": true,
        "dataCharacterEncoding": "UTF-8"
      }
    },
    clientRequestToken = '<request-token>')

Response

{
  "jobId": "<job-id>",
  "jobStatus": "SUBMITTED"
}

DescribeTableDataImportJob API

The DescribeTableDataImportJob API describes a table data import job that was started previously.

AWS CLI example

aws honeycode describe-table-data-import-job \
  --workbook-id '<workbook-id>'
  --table-id '<table-id>'
  --job-id '<job-id>'

Python SDK example

response = honeycode_client.describe_table_data_import_job(
    workbookId = '<workbook-id>',
    tableId = '<table-id>',
    jobId = '<job-id>')

Response

{
    "jobMetadata": {
        "dataSource": {
            "dataSourceConfig": {
                "dataSourceUrl": "<presigned-url>"
            }
        },
        "importOptions": {
            "delimitedTextOptions": {
                "dataCharacterEncoding": "UTF-8",
                "delimiter": ",",
                "hasHeaderRow": true,
                "ignoreEmptyRows": false
            },
            "destinationOptions": {
                "columnMap": {
                    "<price-column-id>": {
                        "columnIndex": 2
                    },
                    "<previous-price-column-id>": {
                        "columnIndex": 3
                    },
                    "<symbol-column-id>": {
                        "columnIndex": 1
                    },
                    "<last-update-column-id>": {
                        "columnIndex": 4
                    }
                }
            }
        },
        "submitTime": 1.60456803175E9,
        "submitter": {
            "userArn": "<submitter-user-arn>"
        }
    },
    "jobStatus": "COMPLETED"
}

After the import job is completed, this is how the table looks.

DescribeTableDataImportJob_Image


API integration with AWS CloudTrail

Amazon Honeycode APIs are integrated with AWS CloudTrail, a service that records all API calls and events for AWS accounts. CloudTrail is enabled when you create an AWS account.

Using the information recorded by CloudTrail, you can identify trends and further isolate activity by attributes, such as what API call was made, when, who made the request, and the IP address.

To learn more about CloudTrail, see the AWS CloudTrail User Guide.


Honeycode activity in CloudTrail

When API activity occurs in Amazon Honeycode apps, the activity is recorded in a CloudTrail event. You can view, search, and download recent events in your AWS account.

For an ongoing record of events in Amazon Honeycode, as well as your other AWS accounts, you can create a trail. A trail enables CloudTrail to continuously deliver events as log files to an Amazon S3 bucket.

All Amazon Honeycode API actions are logged by CloudTrail. For example, any calls to the GetScreenData or InvokeScreenAutomation actions generate entries in the CloudTrail log files.

Every event or log entry contains information about who generated the request. The identity information helps you determine:

  • Whether the request was made with root or AWS IAM user credentials
  • Whether the request was made with temporary security credentials for a role or federated user
  • Whether the request was made by another AWS service

For more information, see the CloudTrail userIdentity Element.

If you don't configure a trail, you can still view the most recent events in the CloudTrail console's in event history. For more information, see Viewing Events with CloudTrail Event History.


Honeycode log files on CloudTrail

CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on. CloudTrail log files aren't an ordered stack trace of the Amazon Honeycode API calls, so they won't appear in any specific order.

The following example shows a CloudTrail log entry of the GetScreenData action.

{
    "awsRegion": "us-west-2",
    "eventID": "3b61e597-4bf1-4c17-aac5-70440468f7d9",
    "eventName": "GetScreenData",
    "eventSource": "honeycode.amazonaws.com",
    "eventTime": "2020-05-21T07:07:39Z",
    "eventType": "AwsApiCall",
    "eventVersion": "1.05",
    "readOnly": true,
    "recipientAccountId": "123456789012",
    "requestID": "73ae2ce0-214b-4dc8-9378-a7a2e2d7aa4e",
    "requestParameters": {
        "appId": "9507a45a-8e7c-4b9b-bdc7-80c29b5ee3e2",
        "maxResults": 10,
        "screenId": "44e50421-8b7c-4074-a6bd-ba5d581ab020",
        "variables": "***",
        "workbookId": "cf8aff9e-3aa3-45e4-b60e-1512a2fa462c"
    },
    "responseElements": null,
    "sourceIPAddress": "12.345.67.890",
    "userAgent": "Jersey/${project.version} (HttpUrlConnection 1.8.0_201)",
    "userIdentity": {
        "accessKeyId": "ACESSKEYIDEXAMPLE12",
        "accountId": "123456789012",
        "arn": "arn:aws:sts::123456789012:assumed-role/honeycode-full-access/HoneycodeTests-cf9c31ee-dcfd-439c-9ba0-8bb68766bcfe",
        "principalId": "PRINCIPALIDEXAMPLE1234:HoneycodeTests-cf9c31ee-dcfd-439c-9ba0-8bb68766bcfe",
        "sessionContext": {
            "attributes": {
                "creationDate": "2020-05-21T07:07:39Z",
                "mfaAuthenticated": "false"
            },
            "sessionIssuer": {
                "accountId": "123456789012",
                "arn": "arn:aws:iam::123456789012:role/honeycode-full-access",
                "principalId": "PRINCIPALIDEXAMPLE1234",
                "type": "Role",
                "userName": "honeycode-full-access"
            },
            "webIdFederationData": {}
        },
        "type": "AssumedRole"
    }
}

Similarly, the following example shows a CloudTrail log entry of the InvokeScreenAutomation action.

{
    "awsRegion": "us-west-2",
    "eventID": "30c82beb-4d38-41ef-9dd2-961ed827412a",
    "eventName": "InvokeScreenAutomation",
    "eventSource": "honeycode.amazonaws.com",
    "eventTime": "2020-05-21T07:07:29Z",
    "eventType": "AwsApiCall",
    "eventVersion": "1.05",
    "readOnly": false,
    "recipientAccountId": "123456789012",
    "requestID": "18e22c8a-495c-4c0f-b3d3-e308541baef5",
    "requestParameters": {
        "appId": "5c132f99-d482-45be-b4f5-6deaf8067d0a",
        "automationId": "124bb3c9-8ab3-4d39-b380-6a43b63dc666",
        "clientRequestToken": "c5f201b9-76ed-4329-bb46-d4a6cc4fc638",
        "rowId": "row:6655a2f2-1e70-45a9-86ec-4d3c63d443b6/f9b70edb-486a-36b4-b72b-89df6f92be44",
        "screenAutomationId": "124bb3c9-8ab3-4d39-b380-6a43b63dc666",
        "screenId": "d2d4b6c6-c5e4-45fc-b342-019132ffb4f8",
        "variables": "***",
        "workbookId": "aa34dd68-2077-440e-abca-470deef13e9b"
    },
    "responseElements": {
        "workbookCursor": 815985817
    },
    "sourceIPAddress": "54.244.61.237",
    "userAgent": "Jersey/${project.version} (HttpUrlConnection 1.8.0_201)",
    "userIdentity": {
        "accessKeyId": "ACESSKEYIDEXAMPLE12",
        "accountId": "123456789012",
        "arn": "arn:aws:sts::123456789012:assumed-role/honeycode-full-access/HoneycodeTests-3941fe61-25ee-4df1-ba85-411bb7e01472",
        "principalId": "PRINCIPALIDEXAMPLE1234:HoneycodeTests-3941fe61-25ee-4df1-ba85-411bb7e01472",
        "sessionContext": {
            "attributes": {
                "creationDate": "2020-05-21T07:07:26Z",
                "mfaAuthenticated": "false"
            },
            "sessionIssuer": {
                "accountId": "123456789012",
                "arn": "arn:aws:iam::123456789012:role/honeycode-full-access",
                "principalId": "PRINCIPALIDEXAMPLE1234",
                "type": "Role",
                "userName": "honeycode-full-access"
            },
            "webIdFederationData": {}
        },
        "type": "AssumedRole"
    }
}

More AWS CloudTrail resources

Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see the following:


FAQs

How many transactions can the APIs handle per second?

Throttling will be per AWS Account. Currently, these are the limits (subject to change):

  • GetScreenData: 25 tps rate/250 tps burst
  • InvokeScreenAutomation: 5 tps rate/50 tps burst
  • StartTableDataImportJob: 1 tps rate/5 tps burst
  • DescribeTableDataImportJob: 5 tps rate/25 tps burst
  • ListWorkbooks, ListTables, QueryTableRows and ListTableRows: 25 tps rate/50 tps burst
  • CreateTableRows, UpdateTableRows, DeleteTableRows, UpsertTableRows: 5 tps rate/25 tps burst

Can I trigger code elsewhere based on an event in Honeycode (e.g. a button being clicked on in a Honeycode app or a row being added to a Honeycode table)?

Yes, you can use webhooks. Please see this article.


Can I use system variables like SYS_USER, conditional visibility, or personalization in screens I intend to use with Honeycode APIs?

No. These concepts are meant to control the app experience for users. However, since there is no concept of logged-in user when interacting with apps programmatically, they will not be expressed when screens are read from the APIs.


Can I get a history of Honeycode API calls made on my account for security analysis and operational troubleshooting purposes?

Yes. To receive a history of Honeycode API calls made on your account, simply turn on CloudTrail in the AWS Management Console. The AWS API call history produced by CloudTrail enables security analysis, resource change tracking, and compliance auditing. Learn more about CloudTrail at the AWS CloudTrail.


Import data APIs:

What is the size limit of the file that can be imported?
The file size should be less than 100 MB. The file that you want to import has to be a delimited text file containing one table, where each line represents a row, and fields separated by a delimiter such as a comma. It can contain up to 1000 rows, including headers. The file can have any number of columns; however, a maximum of 99 columns will be imported by the API. If there are more than 99 columns, it will import the first 99 columns. Also, the user can specify a column mapping if they want to import particular columns.

What file types can I import into Honeycode?
The file that you want to import has to be a delimited text file containing one table, where each line represents a row, and fields separated by a delimiter such as comma, tab or a pipe. The delimiter can be specified at the time of import. Support for other file types is not present at the moment. You could try converting your data to a comma separated (CSV) or tab separated (TSV) format to import into Honeycode.

Would existing automations work on the new data?
Yes. If the table you are importing data into has some automations associated with it, they will continue to trigger for the new data.

Can I import data with emails and rowlink selections?
Yes. As a precursor, the target honeycode table column must be formatted as Contact/Rowlink before importing data. Emails of team members who belong to the org in which the workbook is created will get auto-formatted as a contact. For emails that don’t, the data will still be imported. However, the email will show as plain text and not contact formatted.

Rowlinks will be detected from the input data, as long as the values match the display value of corresponding rowlink.

Can I control the column mapping from my data to the Honeycode table?
Yes. You can specify column mapping in importOptions. For details, check the API Reference page for StartTableDataImport job here. When you click on the import button, you will see an option to match any column from your data to any column in the Honeycode table.

Can I import from more than one file for a table?
Yes. You can import data from more than one file, one after the other. Please note that your billing tier limits will still apply. For instance, if you are in the free tier, you can only have 2500 rows in the table, and import will honor the same limits.

What if I want to import more than 1000 rows?
With one operation, you can only import 1000 rows. However, you can break the csv into multiple files, each containing 1000 rows and call import sequentially for each part. Please note that your billing tier limits will still apply. For instance, if you are in the free tier, you can only have 2500 rows in the table, and import will honor the same limits.

Was this article helpful?
  • Yes
  • No

0 voters

3 Likes
Can Honeycode call api's or endpoints from other services?
Data Integrations
Tables from AWS RDS
Feasibility to connect data to external Database
AWS Quicksight integration
Dynamic link to Excel Online / Google Sheets?
Api Integration with Trello/JIRA ~ Atlassian
Read data from REST API
Does HoneyCode Automation integrates with AWS LAMBDA
How to POST out and receive data to/from an external server?
Show PDF Files from a local server
Dynamo
Catch Hook for incoming webhook payload
API service
Can I connect one app to multiple workbooks?
Integration with AWS Amplify , deployment at client end
Connecting to DocuSign via API
REST or GraphQL API
Hyperlinks to files on local computer
New Year, New Builders!
Use Amazon QuickSight to visualize data from Amazon Honeycode
Sending a list to a webhook
Sending a list to a webhook
Integration/ Deployment
Notify team admin when row limits are reached and state that row limits have been exceeded in error messages
Export as CSV
Connect to AWS QLDB
Using f-strings in Python query_table_rows API call
Using f-strings in Python query_table_rows API call
Working with Table
Release Notes - December 2, 2020
How can I use more than 100,000 rows
Honeycode to AWS Services
How Can i maintain audit of user actions in my application
Implementing Chatbot within Honeycode App
Upload files and download
Rest API interface
Honeycode and Google Sheets
Images link
How to getScreenData of Specific Row?
InvokeScreenAutomation Variable does not exist on screen
Can't send 5 or more items in InvokeScreenApi
Modification des titres des tables
How do you write the variables option for Invoke-screen-automation command?
Rest API for external data creation
How do I upload files to S3?
Modification des titres des tables
Data Ingestion from Mobile App
Honey Code CLI datapull
Connect to external data source like SQL Server
Integration with a 3P DAM (Digital asset management)
Integration with a 3P DAM (Digital asset management)
AWS Platform Integration
Upload files
Way to connect to Redshift?
Amazon Product Advertising API
Integrating with Jira and Google Sheets
Feasibility to connect data to external Database
Amazon Product Advertising API
Ability to sync with Table and Automate Tasks