Smartsheet SDK for Java

This is a Java SDK to simplify connecting to Smartsheet API in Java applications.

Notice

This repo has moved to the Smartsheet Organization on GitHub and can be accessed here.

System Requirements

The SDK supports Java version 1.6 or later.

Installation

There are three different ways to install the SDK. Select the one that fits your environment best:

• Install By Using Maven
• Install By Downloading the Jar File
• Install By Compiling Directly From Source

Install By Using Maven

Add the SDK as a dependency in your project.

<dependency>
  <groupId>com.smartsheet</groupId>
  <artifactId>smartsheet-sdk-java</artifactId>
  <version>[version]</version>
</dependency>

The current artifact version reference can be found here

Install By Downloading the Jar File

SDK packaged as a jar. This jar requires that all of the following dependencies are manually added to the path:

Apache HttpComponents 4.5
Simple Logging Facade for Java 1.7.12
Jackson FasterXML 2.6.2
Jackson Core 2.6.2

You can also navigate to the Sonatype Library Page instead of directly downloading the Jar file.

Install By Compiling Directly From Source

The source code for the jar can be downloaded from Github and then compiled. This can be accomplished using git and maven with the following 3 steps.

git clone https://github.com/smartsheet-platform/smartsheet-java-sdk.git
cd smartsheet-java-sdk
mvn package

Example Usage

To call the API, you will need an access token, which looks something like this example: ll352u9jujauoqz4gstvsae05. You can find the access token in the UI at Account > Personal Settings > API Access.

The following is a brief sample that shows you how to:

• Initialize the client
• List all sheets
• Load one sheet

To initialize the client, you'll need to include the appropriate import directives in your code. For example, the code examples in this section require the following import directives:

import com.smartsheet.api.*;
import com.smartsheet.api.models.*;
import com.smartsheet.api.oauth.*;
import java.io.FileInputStream;
import java.util.*;

// Initialize client
String accessToken = "JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789";

Smartsheet smartsheet = SmartsheetFactory.createDefaultClient(accessToken);

// List all sheets
PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets(
    null,           // EnumSet<SourceInclusion> includes
    null,           // PaginationParameters
    null            // Date modifiedSince
);

System.out.println("Found " + sheets.getTotalCount() + " sheets");

long sheetId = sheets.getData().get(0).getId();      // Default to first sheet

// sheetId = 567034672138842L;                       // TODO: Uncomment if you wish to read a specific sheet

System.out.println("Loading sheet id: " + sheetId);

// Load the entire sheet
Sheet sheet = smartsheet.sheetResources().getSheet(
    sheetId,                // long sheetId
    null,                   // EnumSet<SheetInclusion> includes
    null,                   // EnumSet<ObjectExclusion> excludes
    null,                   // Set<Long> rowIds
    null,                   // Set<Integer> rowNumbers
    null,                   // Set<Long> columnIds
    null,                   // Integer pageSize
    null                    // Integer page
);
System.out.println("Loaded " + sheet.getTotalRowCount() + " rows from sheet: " + sheet.getName());

A simple, but complete sample application is here: https://github.com/smartsheet-samples/java-read-write-sheet

More Java examples available here.

Advanced Topics

For details about logging, testing, how to use a passthrough option, and how to override HTTP client behavior, see Advanced Topics.

Documentation

The full Smartsheet API documentation is here: https://smartsheet.redoc.ly

The generated SDK javadoc is here: https://smartsheet.github.io/smartsheet-java-sdk/apidocs/ (Download as a jar file here.)

Contributing

If you would like to contribute a change to the SDK, please fork a branch and then submit a pull request. More info here.

Version Numbers

Starting from the v2.68.0 release, Smartsheet SDKs will use a new versioning strategy. Since all users are on the Smartsheet API 2.0, the SDK version numbers will start with 2. The 2nd number will be an internal reference number. The 3rd number is for incremental changes.

For example, v2.68.0 means that you are using our 2.0 version of the API, the API is synced internally to a tag of 68, and then if there are numbers after the last decimal, that will indicate a minor change.

Support

If you have any questions or issues with this SDK please post on StackOverflow using the tag "smartsheet-api" or contact us directly at [email protected].

Release Notes

Each specific release is available for download via Github or the Maven repository.

See https://github.com/smartsheet-platform/smartsheet-java-sdk/releases