Linear with Google Sheets

Get, update, and create Linear issues from Google Sheets

This guide shows you how you can use the Fusebit Add-On For Google Sheets to:

  • Import Linear issues into Google Sheets
  • Update Linear issues from within Google Sheets
  • Create new Linear issues from within Google Sheets
802802

Import Linear issues to Google Sheets

Before you continue, you must complete the setup steps from Getting Started with Google Sheets and have a Google Spreadsheet configured and ready to use with the Fusebit Add-On. Follow this guide in sequence as sections build on one another.

Overview

In this guide, we will create a Node.js function that uses a Fusebit Connector for Linear to enable you to get, update, and create Linear issues using the FUSEBIT spreadsheet function provided by the Fusebit Add-On for Google Sheets.

We will start by adding a Fusebit Connector for Linear along with relevant data manipulation Snippets to the solution and authorizing access to your Linear subscription. Then, we will use the Linear snippets to implement Node.js functions that expose the get, update, and create functionality to the Google Spreadsheet.

When we are done, you will be able to query your Linear issues from within Google Spreadsheet on demand, update Linear issues by changing the data in the Google Spreadsheet, as well as create new Linear issues from with your spreadsheet.

Add Snippets and Authorize Linear

In your Google Spreadsheet, go to Extensions | Fusebit | Open, click Edit, and in the Fusebit Editor that will open in a separate tab, select Snippets. In the Add Snippet dialog that shows up, type linear in the search field, and then choose the Linear - Get issues snippet and click Add:

26502650

Add "Linear - Get issues" snippet in the Fusebit Editor

Repeat the snippet adding gesture to add two more snippets: Linear - Create a new issue and Linear - Update an existing issue. If you scroll down to the bottom of integration.js, you should see three new Node.js functions added: linearGetIssues, linearUpdateIssue, and linearCreateIssue. We will be using them in later sections. You can read more about the Fusebit Connectors and Snippets here.

Back in the Fusebit Editor, click Run and follow the prompts to Authorize access to your Linear subscription:

26502650

Authorize access to Linear

You are now set up to start configuring your spreadsheet and writing some Node.js code.

Importing Issues from Linear

Set up a sheet in your Google Spreadsheet as follows:

16081608

Set up spreadsheet for importing Linear issues

Using the Fusebit Add-On, you can configure arbitrarily flexible querying conditions for your Linear issues. In this guide, we demonstrate this capability by only showing the Linear issues that were created recently. Cell B1 will hold an input parameter describing the number of recent days to filter by. Take note of the checkbox in cell B2 - it is part of the mechanism that will allow you to refresh data on demand.

We intend the Linear issues to be listed one per row starting from cell C2, and we will be showing only the ID, Priority, and Title for each issue in this guide. Your implementation can choose arbitrary projection of the issue.

With the spreadsheet set up, let's switch back to the Fusebit Editor tab. (If you closed it, you can always reopen it with Extensions | Fusebit | Open and then Edit). This is where we will implement a Node.js function that will use the Linear - Get issue snippet we added previously. Locate the declaration of the googleSheetsFunctions object around line 9 in integration.js, and add a new property to it that defines and implements the Node.js function you will be able to call from Google Spreadsheets:

linearGetRecentIssues: async (ctx, data) => {
  // get number of recent days from input
  const numberOfDays = +(Array.isArray(data) ? data[0][0] : data) || 1;
  // compute cutoff ISO date
  const createdSince = new Date(Date.now() - numberOfDays * 24 * 60 * 60 * 1000).toISOString();
  // get Linear issues created after cutoff date
  const issues = await linearGetIssues(ctx, { filter: { createdAt: { gt: createdSince } } });
  // format result to send to spreadsheet as 2D array, one issue per row
  const result = issues.nodes.map(i => [ i.identifier, i.priority, i.title ])
  return result;
},

The function first processes the input data from the Google Spreadsheet to determine the number of days for which recent issues should be returned (which we will source from cell B1). It then translates that number of days to a cutoff date in ISO format. Next, it calls the linearGetIssues snipped we previously added to get the matching issues. Lastly, the results are formatted into a two-dimensional array that is returned back for rendering in the Google Spreadsheet. You can read more about the programming here.

With the code in place, let's go back to the spreadsheet and call the Node.js function we just implemented by adding =FUSEBIT(B1:B2,"linearGetRecentIssues") in the C2 cell. The function evaluates by invoking the linearGetRecentIssues Node.js function we've added in the Fusebit Editor, and the results are displayed in the spreadsheet. The function re-evaluates by calling the Node.js function again every time the input parameters change - either the number of days in cell B1, or the checkbox status in cell B2:

802802

Calling the Node.js function from Goggle Sheets to get Linear issues

Congratulations! You've just implemented an import of Linear issues matching specific criteria to Google Sheets. You can refactor this mechanism in a variety of ways:

  • Change the issue selection criteria by designing a different set of input values passed to the FUSEBIT function.
  • Change the projection of the issue by modifying the transformation of Linear issues into data returned to Google Sheets in the Node.js function.
  • Implement any custom filtering or post-processing of issues in Node.js.

Now, let's explore updating Linear issues from Google Sheets.

Updating Linear Issues from Goggle Sheets

Setup another sheet in your Google Spreadsheet as follows:

17101710

Updating Linear issues from Google Sheets

Notice the format of the A-C columns is similar to the output generated in the previous section by importing Linear issues into Google Sheets. You can in fact Copy & Paste Special - Values Only the list of issues from import to create this view. Column D will be used to report status of the update operation.

The way this mechanism will work is that every time data in columns B or C changes, the corresponding issue from column A will be updated, and the timestamp of the update reflected in column D. Let's get started.

Back in the Fusebit Editor on the separate tab (if you don't see it, use Extensions | Fusebit | Open, then click Edit), find the googleSheetsFunctions object and add another property to it which implements the Node.js logic to update an issue:

linearUpdateIssues: async (ctx, data) => {
  const result = [];
  // process each row as a separate issue
  for (const row of data) {
    // decompose columns into issue properties
    const [ identifier, priority, title ] = row; 
    // update Linear issue
    try {
      await linearUpdateIssue(ctx, identifier, { priority, title });
      // return last updated date
      result.push([new Date()]);
    }
    catch (e) {
      // return error message
      result.push([e.messsage]);
    }
  };
  return result;
},

The function accepts a rectangular range of data from a Google Spreadsheet. It assumes one Linear issue is represented by each row, and the first three columns contain the identifier, the priority, and the title of the issue. The function iterates over every row in the range, breaks up the columns into the relevant properties, and then calls the linearUpdateIssue snippet we previously added on that issue. If the update is successful, the result for this issue will be the timestamp of the update, or the error message otherwise. When this function is done, it returns a two-dimensional array back to Google Sheets, with each row representing the update status of the respective issue from the input range. Note that the Linear API for updating issues is idempotent - if no updates were actually performed, the issue is left intact.

Save the changes in the Fusebit Editor, then go back to the Google Spreadsheet to make use of it:

802802

Updating Linear issues from Google Sheets

Notice that any change in the input range of the function (A2:C2 in the example above) causes all issues in the range to be updated, even the ones that do not require it. Since Linear APIs are idempotent, it is not a problem, but if you want to limit the number of API calls, you can choose to apply the =FUSEBIT({range},"linearUpdateIssues') function to individual rows instead by replicating the formula in cells D2:D3.

Congratulations! You can now update your Linear issues directly from Google Sheets! You can refactor this mechanism to meet your specific needs by:

  • Changing the projection of the issues and the specific properties you want to support updating.
  • Applying additional validation logic inside of the Node.js function.
  • Implementing additional side effects inside of a Node.js function, for example sending a message to Slack when an issue was closed.

Now, let's move on to the last topic - creating new Linear issues from Google Sheets.

Creating Linear Issues from Google Sheets

After the previous two sections, no mechanisms described here should be new. Set up a new sheet in your spreadsheet as follows:

13401340

Creating new Linear issues from Google Sheets

This is set up similarly to the sheet for updating issues, except the issue identifier column is missing as linear issue identifiers as server-assigned. Columns A and B represent the new issues to be created, and column C will contain the status of their creation.

Back in the Fusebit Editor on the separate tab (again, if you don't see it, use Extensions | Fusebit | Open, then click Edit), find the googleSheetsFunctions object and add yet another property to it which implements the Node.js logic to create a new issue:

linearCreateIssues: async (ctx, data) => {
  const result = [];
  // process each row as a separate issue
  for (const row of data) {
    // decompose columns into issue properties
    const [ priority, title ] = row; 
    // create Linear issue
    try {
      await linearCreateIssue(ctx, { priority, title });
      // return created date
      result.push([new Date()]);
    }
    catch (e) {
      // return error message
      result.push([e.messsage]);
    }
  };
  return result;
},

Notice the logic and flow here is very similar to the previously implemented linearUpdateIssues function. The issues to be added are passed in as rows of the input range, they are broken into the priority and title properties before being passed to the linearCreateIssue snippet we added previously. The result for every row is the date the issue was added or an error message if there was one. This logic could be easily merged with the linearUpdateIssues function to create a function with an upsert semantics, but we treat it separately here for the clarity of the example.

Save the changes in the Fusebit Editor, then go back to the Google Spreadsheet to make use of the new function:

802802

Creating new Linear issues from Google Sheets

Once the function reports the creation timestamps, the issues had been created in Linear. Note that it is worthwhile to remove the =FUSEBIT(...,"linearCreateIssues") rule from cell C2 to avoid accidentally creating duplicates should the Google Spreadsheet choose to re-evaluate all functions, which can be triggered by a variety of circumstances.

Congratulations, you are now able to import, update, and create new issues in Linear directly from Google Sheets. Remember the capabilities of the Fusebit Add-On go beyond Linear - with the power of Node.js, NPM, and Fusebit Connectors, you can connect to any API and data source out there and perform complex data mashups and manipulations.


Did this page help you?