Stepping into the Construction scene
PlanGrid, a blueprint app used by construction companies, is one of Kloudless’ earliest customers. PlanGrid uses the Kloudless File Explorer to allow contractors to transfer documents and drawings from and to cloud storage services such as Box, Dropbox, Google Drive, and more, using Kloudless’ unified Cloud Storage API. In the recent past, we’ve noticed several additional construction apps begin to use Kloudless for very similar uses. Cloud storage integrations prove valuable since a lot of construction software is centered around document workflow and processes.
However, cloud storage isn’t the only location valuable documents and files are present at. Kloudless receives numerous inquiries from construction software companies to integrate with other construction tools themselves. Recently, the number of inquiries proved significant enough that Kloudless decided to step into the construction space and add document data from connectors such as PlanGrid to our Storage API. In this post, we’ll discuss our experience working with the PlanGrid API, obstacles encountered, and how we moved past them.
The PlanGrid API
PlanGrid provides detailed docs on their API online, and has a straightforward process to gain access to a test account to use with their API. This open API approach is crucial to any app’s success today. Apps that encourage developer adoption and mindshare work well with the other software utilities their customers love, making them stickier and more valuable in their customers’ eyes. It’s easy to see why PlanGrid’s rapid growth inspired Autodesk to acquire them for $875 million!
Accessing files and folders
The Kloudless abstraction layer provides a single interface to access and modify files and folders. Kloudless relies on upstream provider API endpoints to perform these actions. However, the various upstream cloud services may not necessarily provide endpoints with similar functionality. One example of this is accessing folder contents in PlanGrid.
It is technically possible to create, edit, and delete folders via the PlanGrid web UI. However, a quick review of their API Docs and some tests with API requests reveal three major concerns:
- Apps can list files under the whole project, but not under an individual sub-folder.
- The listing process only lists files, and not folders.
- There are no API endpoints to create, update, or delete folders.
Addressing the concerns above.
One of the core value propositions of the Kloudless layer is to “fill in the gaps” and augment underlying APIs where possible. In this scenario, we’d like to offer the same functionality Kloudless makes available for API requests to Box to PlanGrid as well.
It is still possible to construct the entire file/folder tree structure by listing all files under the whole project, and then filtering out the ones required based on a specific parent folder. It’s not the most efficient approach, but it’s the most straightforward way to implement this capability!
However, we also took a closer look at how the web UI works. Reviewing the browser’s web requests during page load, the web UI appears to use an undocumented endpoint,
/projects/:projectUid/documents, to access granular levels of document data. Check out an example screenshot of the data returned below.
The other “gap” Kloudless steps in to solve is around folder creation. The PlanGrid API doesn’t explicitly support creating new, empty folders. However, it’s possible to use the File Upload API endpoint to provide a full path to a non-existent location. This indirectly creates a folder, meeting our API’s requirements.
Uploads in PlanGrid
File uploads via the PlanGrid API consist of the three following steps:
- A POST request that specifies the
content_typeof the file (an actual MIME type), the file
name, and a
- An actual file upload POST request to the Amazon S3 URL returned from the step above, along with some additional information from that step.
- (Optional) A GET request to notify the Plangrid API that the upload is complete. Note that this is usually automatically handled by S3.
Since the PlanGrid API doesn’t provide Folder-related endpoints, it isn’t a surprise that the API only requires a folder name to upload content to rather than a unique ID that identifies an individual folder. If there are multiple identical folders in the “tree”, and a leaf folder name is provided rather than a full path, PlanGrid simply picks the first matching folder via a breadth-first search. A full path name such as
first-folder-in-project/folder2/your-file.pdf avoids this ambiguity and also assists with the folder creation mentioned earlier.
Coming Soon: A PlanGrid Connector
Check out Kloudless for a set of standard data models and endpoints to access several different cloud apps with a single integration. Kloudless handles complexities such as the ones described above for PlanGrid for each service we support.
Keep an eye out for our brand new PlanGrid connector that launches this week. The initial release includes support for document data via the Storage API and the File Explorer. We’d love to hear feedback or suggestions at firstname.lastname@example.org!