Workiva Support Center

Introduction

This guide will show you how to use the Workiva API to import a file into Wdata.

If you wish to automate the import of a dataset file into a Wdata table, but do not wish to use chains with the Workiva connector, you can instead use the Workiva API directly from chains with the HTTP connector or from any external software capable of interacting with a REST API secured with OAuth 2.0.

Initial Setup

First you need to create an API grant which will generate a Client ID and secret. This can be done by any Workiva user account with at least "Workspace Owner" or "Org Security Administrator" permissions and by following the instructions provided here.

Authentication

Once you have the API grant correctly setup, the first step in the communication with the API is to gain authentication. This uses an industry standard oauth 2.0 bearer token exchange and requires a POST call as detailed in the instructions here.

Import

There are two required steps to load data into into a Wdata table using the Workiva API:

1. Upload the file into your chosen Wdata table (https://developers.workiva.com/wdata-v1/wdata-uploadfile/). This will add your file as a dataset in the table with status "staged". Therefore, the new data will not appear in any queries or views on the table at this point.
2. Import the file (https://developers.workiva.com/wdata-v1/wdata-importfile/). The "Id" you receive in the response from the upload can then be used in the property "fileId" to import the file and, if successful, add the data into the table and make it available in queries and view.

With Examples

Key

In the examples below, URLs are shown for the EU platform; for the US or APAC, the "eu" should change to "app" or "apac" respectively.

1. Upload

   Upload the file into your chosen Wdata table: https://developers.workiva.com/wdata-v1/wdata-uploadfile/

   Example:

   POST: {baseURL}/api/v1/file 
   Headers: 
   Content-Type: multipart/form-data; boundary="boundary" 
   Body: 
   --boundary 
   Content-Disposition: form-data; name="delimiter" 
    
   semicolon 
   --boundary 
   Content-Disposition: form-data; name="tableId" 
    
   {tableId} 
   --boundary 
   Content-Disposition: form-data; name="file"; filename="filename.csv" 
   Content-Type: text/plain 
    
   fruit;quantity 
   Apple;133 
   Apricot;175 
   Avocado;182 
   Banana;187 
   Bilberry;160 
   Blackberry;178 
   Blackcurrant;102 
   Blueberry;156 
   Currant;194 
   Cherry;182 
   Cherimoya;169 
   Clementine;165 
   Date;112 
   Damson;164 
   Durian;157 
   Eggplant;189 
   --boundary-- 

2. Import

   Then use the "Id" you receive in the response as the "fileId" to import the file in this: https://developers.workiva.com/wdata-v1/wdata-importfile/

   Example:

   POST: {baseURL}/api/v1/table/{tableId}/import 
   Headers: 
   Content-Type: application/json 
   Body: 
   { 
       "delimiter":";", 
       "fileId":"{fileId}" 
   } 

   Note: This request only initiates the file import and the response is sent without waiting for it to succeed or fail.

Check Status

It's not required but will be good practice in most use-cases to confirm and log/report if the file import was successful or not. This can be done with the following two GET requests.

1. To confirm the import file endpoint has successfully imported the file, you should use (poll) the Retrieve a single file endpoint for the same {fileId} from the import and then check the response for your file.

   Example:

   GET: {baseURL}/api/v1/file/{fileId}
   Headers: 
   Content-Type: application/json 

2. If the status is "IMPORTING", the import is still in progress so you should pause the process for a period before repeating the previous request (poll).
3. A status of "IMPORTED" indicates the file was imported successfully.
4. If the status of your file is still "STAGED" and the "numErrors" is greater than zero then the file has failed to import and you can use the Retrieve errors endpoint to fetch the error messages that occurred.

Troubleshooting

If you cannot make any requests to the API (401 Unauthorized error)

• Check you've used the correct URL prefix for the location of your Workiva Workspace.
• Check you're using the correct Client ID and Secret in your request without any spaces before or after.

Authentication works but subsequent requests do not (404 or 500 errors)

• Check the user specified in the API grant you've created has access to the specified Wdata table ID.
• Check the Wdata table is in the same workspace as the API grant.
• Check you're using the correct file IDs without any spaces before or after.
• Check your headers, particularly the "Content-Type", match the documentation.

My file uploads successfully but errors on import

• Check you specified the correct delimiter.
• Make sure the data in your file is in a flat file format with the headers in row 1 from column A and the data in row 2 from column A.
• Make sure the number of header columns match the number of data columns.
• Check the data types match those specified in the Wdata table setup.
• Retrieve errors related to the file import for further troubleshooting