The integration with Google Forms takes advantage of the Next Matter public API. To trigger a new instances of a process when a Google Form is submitted, a POST request must be sent to the NM APIs /instances endpoint. The integration example before additionally used form response data to populate fields in the first active step of the new process instance.

Pre-requisites

  • Basic Javascript knowledge

  • Apps Script reference documentation - https://developers.google.com/apps-script/reference/

  • Google Form ID - this can be found in the URL of the Form page, which will look similar to this: https://docs.google.com/forms/d/<form_id>/edit; copy the form ID value as it will be required in the script.

  • Next Matter API key for the target organisation - Please reach out to the Next Matter team and we will safely submit the key to you.

  • Next Matter process ID - this is the process which we want to have the form create a new instance of, and is the last numeric part of the URL when editing the process. For example: https://app.nextmatter.com/app/editor/edit/123 (123 being the process ID)

Step 1: Create the Next Matter process and the according fields.

Step 2: Create the Google Form

This is done via https://docs.google.com/forms/. For details on how to build a Google Form, please refer to https://support.google.com/a/users/answer/9991170 as this part will not be covered here.

When the basic form is ready, the next step is to create an Apps Script that will use the NM API, and then attach a form trigger to that script, so that it executes whenever a new form response is submitted.

Step 3: Create the form Script

To create a new script, in the forms page click the top right corner menu icon, and select the "Script editor" option. Alternatively, navigate to https://script.google.com/home/ and click "New Project". This will open the script editor with a function template pre-populated.

Sample Code

// Process and action references, as well as response item sequence must match your target process

const API_KEY = "ADD_TARGET_ORG_API_KEY_HERE";
const FORM_ID = "ADD_SOURCE_GOOGLE_FORM_ID_HERE";

const PROCESS_ID = "ADD_NM_TARGET_PROCESS_ID_HERE";
const INSTANCES_URL = "https://core.nextmatter.com/api/instances/";

const fetchOptions = {
muteHttpExceptions: true,
method: "post",
contentType: "application/json",
headers: {
Authorization: `Api-Key ${API_KEY}`,
},
};

function submitForm(e) {
if (!e || !e.response) {
return;
}

let apiResponse = UrlFetchApp.fetch(INSTANCES_URL, {
...fetchOptions,
payload: JSON.stringify({
name: "Product form " + new Date().toUTCString(),
process: `https://core.nextmatter.com/api/processes/${PROCESS_ID}/`,
tags: [`form:${FORM_ID}`, `response:${e.response.getId()}`],
}),
});

let responseCode = apiResponse.getResponseCode();

if (!apiResponse || ![200, 201].includes(responseCode)) {
Logger.log("Next Matter API call failed");
if (apiResponse) {
Logger.log(apiResponse.getContentText());
}
return;
}

const instance = JSON.parse(apiResponse.getContentText());
const { id, active_step_ids } = instance;

Logger.log(`Instance ID: ${id}`);

const completeStepUrl = `${INSTANCES_URL}${id}/complete_step/`;
const responses = e.response.getItemResponses();

const responseCollectionItems = responses[5].getResponse();
const allCollectionItems = responses[5]
.getItem()
.asCheckboxItem()
.getChoices()
.map((choice) => ({
name: choice.getValue(),
checked: responseCollectionItems.includes(choice.getValue()),
}));

// Action IDs must match your target process. These ones are just used for demo purposes.
const actions = [
{
action_id: 19566,
input_object: {
inputValue: responses[0].getResponse(),
},
},
{
action_id: 19568,
input_object: {
inputValue: responses[1].getResponse(),
},
},
{
action_id: 19569,
input_object: {
date: new Date(responses[2].getResponse()).toISOString(),
},
},
{
action_id: 19572,
input_object: {
itemSelected: responses[3].getResponse(),
},
},
{
action_id: 19573,
input_object: {
radioItemSelected: responses[4].getResponse(),
},
},
{
action_id: 19574,
input_object: {
allItems: allCollectionItems,
itemsChecked: allCollectionItems
.filter((item) => item.checked == true)
.map((item) => item.name),
itemsNotChecked: allCollectionItems
.filter((item) => item.checked == false)
.map((item) => item.name),
numberOfItemsChecked: responseCollectionItems.length,
numberOfItemsNotChecked:
allCollectionItems.length - responseCollectionItems.length,
},
},
{
action_id: 19575,
input_object: {
inputValue: responses[6].getResponse(),
},
},
];

Logger.log(JSON.stringify(actions));

apiResponse = UrlFetchApp.fetch(completeStepUrl, {
...fetchOptions,
payload: JSON.stringify({
step_id: active_step_ids[0],
actions,
}),
});

responseCode = apiResponse.getResponseCode();

if (!apiResponse || ![200, 201].includes(responseCode)) {
Logger.log("Next Matter API call failed");
if (apiResponse) {
Logger.log(apiResponse.getContentText());
}
return;
}

Logger.log(apiResponse.getContentText());
}

Step 4: Create the form Submit Trigger

In the Google Apps Script console, go to the "My Projects" section. Click on the right-hand side menu icon for your newly added project and select "Triggers". Click the "Add Trigger" button. Configure the trigger as per the example below (event type should be "On form submit"), and click save.

Step 5: Testing

In the Google Apps Script console open the "My Executions" section.

In a new browser tab, fill out the target form and submit your response. If everything worked, the submission trigger will fire, and will log the response from the NM API as per the example below, and will be marked as "Completed". In the Next Matter UI a new instance of the target process should be created at this point, with the first step populated with form data and completed.

On failure the execution will be marked as "Failed", and may (depending on type of failure) show additional details, like in the example below.

Did this answer your question?