How to Get Started Making Manuscript Integrations

Every team can craft great software, you just need the best tools and the right information.

The ‘best tools’ part of this is particularly important. Freeing your team to be able to use the right tools for the job, the tools they actually want to use, is not only empowering, but in our experience leads to better results. So, while Manuscript provides all you need to make great software, including project management, issue tracking, and support functionality. Whenever you want to use another tool in your workflow, we enable you to use it seamlessly with Manuscript. That’s why we provide robust integrations with other best of breed tools like Slack, GitHub and Google Docs that are free to use, and fully customizable.

But if there isn’t an existing integration for the tool you use, you don’t need to start coding it from scratch. You can remix full, working apps shared by the Manuscript community on Glitch, and edit them however you need to. Glitch provides a browser-based code editor to modify your integrations, and instantly hosts and deploys them as you make changes. So with nothing to install, you can get straight to work on your integration and even pair program with colleagues in real-time.

What’s more, to help you get started we’ve provided a “Hello World” starter project and it’s this project that I want to walk you through in this post, so you can see just how easy it is to start working with the Manuscript API and integrate the tools you use with Manuscript.

The “Hello-Manuscript” project provides a form, which takes user input and posts it to your Manuscript account, either as a new case or as a new comment in an existing case.

It makes use of our Manuscript NPM package, which makes it easy to work with the Manuscript API in Node.js. And it’s a handy starting point for creating your own integrations between Manuscript and the tools you use.

The only required parts of a Manuscript integration relate to the ability for users of it to add and edit the integration from the integrations page within Manuscript. In our hello-manuscript example, these important parts of the code are in server.js, so we’ll start there.

The integrations page within your Manuscript instance hits this endpoint whenever a user clicks the integration tile. In this sample app, we’re simply redirecting to a pre-populated webform. You’ll probably want to do something more complex, such as storing the authentication data in a database instance.

2. The other required thing is a GET route for the ‘/status’ endpoint. This should consume a site name (in query params) and send back the status of the integration for that particular site. The response will look like one of these:

Manuscript will use this response to display the status of the integration on the integrations page.

With those things setup, lets take a look at the more interesting part of the code: the bit that passes the webform data into Manuscript. It does this with a POST route for /push beginning on line 35:

It uses the Manuscript API through use of our NPM package to pass the title, text and optional case ID to Manuscript. So it’s this code that you should modify to pass data from another tool into Manuscript, instead of submitted user input.

Lastly, at some point, you’ll likely want to remove the other files in the project, like index.handlebars, style.css, and client.js. They just provide something nice to look at while you hit the app’s URL, so are only useful if you too need to provide a visible front-end such as a form to capture input.

And that’s it. If you’re looking for more involved examples, take a look at the Manuscript community app gallery, where you can view the code and remix other working integrations.

To understand more about what you can do, take a look at the Manuscript API docs, or learn more about Manuscript and the tools it integrates with.