top of page
Katapult Engineering

Create Your Own Tools And Extend The Platform

You can create your own APIs to interact with Katapult Pro (using our API) to allow you to build custom tooling that is entirely in your control.  While there are a multitude of ways to do this, it doesn’t have to require the overhead of setting up and maintaining your own server; and one of the easiest ways to get started is leveraging Cloudflare Workers.  


Cloudflare workers allow you to run custom code in response to REST requests, just like the requests generated by Katapult Pro Web Tools. (Web Tools, in Katapult Pro, is a type of mapping tool you can create from your Model Editor.) For this Quick Start guide, we will assume that you already created a Cloudflare account, which is free and takes just a few seconds.


Once you are in the Cloudflare dashboard, you can click on “Compute (Workers)” in the sidebar (see below image).


This will take you to the "Get Started" page (depicted below). You can set up git integrations from Github or Gitlab for more control over the development process. For simplicity, we’re going to start with the “Hello World” Template.


You can rename the worker at this screen (seen below) if you want to, and click “Deploy.”


Your worker is now created and deployed! Click “Edit code” (seen below) to open the built-in editor and test environment.


Testing And Editing Your Worker

In order to allow access to the endpoint from outside domains (like katapultpro.com), we need to add cross origin requests on the response. We’re going to add https://katapultpro.com, but to allow access for any domains, you could replace that domain with an asterisk (*). Then we just add those headers to the response object, as below:

JavaScript
const headers = new Headers();
headers.append('Access-Control-Allow-Origin', 'https://katapultpro.com');

export default {
  async fetch(request, env, ctx) {
    return new Response('Hello World!', {headers});
  },
};

We now have a functional API endpoint, which we can test by switching to the HTTP tab of the testing pane, and clicking the run button with the ⟳ icon. (Reference the image below.)

We can see that when this URL receives a “GET” request, it responds with "Hello World!" This is great, but let’s make it interact with Katapult Pro.


We’re going to add some boilerplate code to help us parse the query parameters:


First, we'll add a helper function to find a given parameter given its key, 

JavaScript
const getParamValue = (searchKey, params) => {
  return params.reduce(
    (acc, cur) => cur.split('=')[0] === searchKey ? cur.split('=')[1]:    acc, null
  );
}

And then some code to actually grab the parameters and put them into a form we can use:

JavaScript
// get the URL tail (everything after '/api')
const urlTail = request.url.split('/api')[1];

//split the query parameters
const allParams = urlTail?.split('?')?.[1]?.split('&');

const jobId = getParamValue('job_id', allParams);
const nodeId = getParamValue('node_id', allParams);
const apiKey = getParamValue('api_key', allParams);

Then we can build our new request, which will be sent to the Katapult Pro API:

JavaScript
// The URL of the Katapult Pro API endpoint we want to use
const newRequestURL = 'https://katapultpro.com/api/v3/jobs/${jobId}/nodes/${nodeId}?api_key=${apiKey}';

// The data we want to send to the Katapult Pro API
const requestBody = {
  add_attributes: {
    note: 'This is a note from my new awesome API tool!'
  }
};

// The full request payload
const updateOptions = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(requestBody)
};

// The actual request to the Katapult Pro API
await fetch(newRequestURL, updateOptions);

Once we put this all together, and click deploy (see screenshot below), we have a functional endpoint that will integrate with Katapult Pro.


Now we need to configure a mapping tool in Katapult Pro to reach out to that endpoint. In the Model Editor, select your job model and create a new tool. Select an icon and color, then choose “Run Web Tool” as the "Tool Action" before pasting in the URL of our Cloudflare endpoint.


Now, in order for Cloudflare to know where to perform this action, we need to add some query parameters to this URL, so we’re going to add them after a question mark (?), separated by ampersands (&). 

?job_id=$(job_id)&node_id=$(node_id)&api_key=$(api_key)

The tool will replace $(job_id) with the job Id where the tool was initiated, and do the same for any other parameters we have defined above. It will also populate the user’s API key, so that the Cloudflare endpoint can authenticate as the Katapult Pro user, and do this work on their behalf.


Finally, we will select “API Call” at the bottom for "Endpoint Action," and add it to our toolset.


Now we can open any Katapult Pro job in this model, and run the tool!

As you can see, we created a note using the API, just like we expected.


Next Steps

For simplicity, this guide ignored any error handling and merely showed a basic integration you can build with Cloudflare Workers and Katapult Pro, but you can do much more than simply adding a note. Your API endpoint can reach out to the Katapult Pro API with several requests to gather data and then use that information to add new nodes, connections, sections, upload photos, or any number of different things.  


Suppose we wanted to create a tool that changed the connection type of all connections to a node. We could easily fetch the connection data on the job, filter the list to adjacent connections, and send requests to change each of their types.  Or perhaps we wanted to connect to a company's legacy GIS, and copy data into Katapult Pro based upon the municipality of a node or its elevation.  To see what you can do through the Katapult Pro API, check out the documentation on our v3 API.


We know that every user and every company has their own unique use case, and we want to put the power in the hands of the user, to work the way they need to, with the custom tools they need.


bottom of page