✨ Add Formstack Trigger (#2066)

* add initial formstack integration configuration

* implement getForms for formstack integration

* implement oauth2 authentication for formstack

* fix formstack color

* enable formstack webhook registration

* remove typeform types

* implement formstack fetch

* ⚡ Improvements to #1673

* ⚡ Improvements

* ⚡ Make work with new async credentials

* ⚡ Improvements

Co-authored-by: Aniruddha Adhikary <aniruddha@adhikary.net>
Co-authored-by: Jan Oberhauser <jan.oberhauser@gmail.com>

packages/nodes-base/credentials/FormstackApi.credentials.ts

@@ -0,0 +1,19 @@
+import {
+	ICredentialType,
+	NodePropertyTypes,
+} from 'n8n-workflow';
+
+
+export class FormstackApi implements ICredentialType {
+	name = 'formstackApi';
+	displayName = 'Formstack API';
+	documentationUrl = 'formstack';
+	properties = [
+		{
+			displayName: 'Access Token',
+			name: 'accessToken',
+			type: 'string' as NodePropertyTypes,
+			default: '',
+		},
+	];
+}

packages/nodes-base/credentials/FormstackOAuth2Api.credentials.ts

@@ -0,0 +1,49 @@
+import {
+	ICredentialType,
+	NodePropertyTypes,
+} from 'n8n-workflow';
+
+const scopes: string[] = [];
+
+export class FormstackOAuth2Api implements ICredentialType {
+	name = 'formstackOAuth2Api';
+	extends = [
+		'oAuth2Api',
+	];
+	displayName = 'Formstack OAuth2 API';
+	documentationUrl = 'formstack';
+	properties = [
+		{
+			displayName: 'Authorization URL',
+			name: 'authUrl',
+			type: 'hidden' as NodePropertyTypes,
+			default: 'https://www.formstack.com/api/v2/oauth2/authorize',
+			required: true,
+		},
+		{
+			displayName: 'Access Token URL',
+			name: 'accessTokenUrl',
+			type: 'hidden' as NodePropertyTypes,
+			default: 'https://www.formstack.com/api/v2/oauth2/token',
+			required: true,
+		},
+		{
+			displayName: 'Scope',
+			name: 'scope',
+			type: 'hidden' as NodePropertyTypes,
+			default: scopes.join(' '),
+		},
+		{
+			displayName: 'Auth URI Query Parameters',
+			name: 'authQueryParameters',
+			type: 'hidden' as NodePropertyTypes,
+			default: '',
+		},
+		{
+			displayName: 'Authentication',
+			name: 'authentication',
+			type: 'hidden' as NodePropertyTypes,
+			default: 'header',
+		},
+	];
+}

packages/nodes-base/nodes/Formstack/FormstackTrigger.node.ts

@@ -0,0 +1,199 @@
+import {
+	IHookFunctions,
+	IWebhookFunctions,
+} from 'n8n-core';
+
+import {
+	IDataObject,
+	INodeType,
+	INodeTypeDescription,
+	IWebhookResponseData,
+} from 'n8n-workflow';
+
+import {
+	apiRequest,
+	getFields,
+	getForms,
+	getSubmission,
+	IFormstackWebhookResponseBody
+} from './GenericFunctions';
+
+export class FormstackTrigger implements INodeType {
+	description: INodeTypeDescription = {
+		displayName: 'Formstack Trigger',
+		name: 'formstackTrigger',
+		icon: 'file:formstack.svg',
+		group: ['trigger'],
+		version: 1,
+		subtitle: '=Form ID: {{$parameter["formId"]}}',
+		description: 'Starts the workflow on a Formstack form submission.',
+		defaults: {
+			name: 'Formstack Trigger',
+			color: '#21b573',
+		},
+		inputs: [],
+		outputs: ['main'],
+		credentials: [
+			{
+				name: 'formstackApi',
+				required: true,
+				displayOptions: {
+					show: {
+						authentication: [
+							'accessToken',
+						],
+					},
+				},
+			},
+			{
+				name: 'formstackOAuth2Api',
+				required: true,
+				displayOptions: {
+					show: {
+						authentication: [
+							'oAuth2',
+						],
+					},
+				},
+			},
+		],
+		webhooks: [
+			{
+				name: 'default',
+				httpMethod: 'POST',
+				responseMode: 'onReceived',
+				path: 'webhook',
+			},
+		],
+		properties: [
+			{
+				displayName: 'Authentication',
+				name: 'authentication',
+				type: 'options',
+				options: [
+					{
+						name: 'Access Token',
+						value: 'accessToken',
+					},
+					{
+						name: 'OAuth2',
+						value: 'oAuth2',
+					},
+				],
+				default: 'accessToken',
+				description: '',
+			},
+			{
+				displayName: 'Form Name/ID',
+				name: 'formId',
+				type: 'options',
+				typeOptions: {
+					loadOptionsMethod: 'getForms',
+				},
+				default: '',
+				required: true,
+				description: 'The Formstack form to monitor for new submissions',
+			},
+			{
+				displayName: 'Simplify Response',
+				name: 'simple',
+				type: 'boolean',
+				default: true,
+				description: 'When set to true a simplify version of the response will be used else the raw data.',
+			},
+		],
+	};
+
+	methods = {
+		loadOptions: {
+			getForms,
+		},
+	};
+
+	// @ts-ignore
+	webhookMethods = {
+		default: {
+			async checkExists(this: IHookFunctions): Promise<boolean> {
+				const webhookUrl = this.getNodeWebhookUrl('default');
+				const webhookData = this.getWorkflowStaticData('node');
+
+				const formId = this.getNodeParameter('formId') as string;
+
+				const endpoint = `form/${formId}/webhook.json`;
+
+				const { webhooks } = await apiRequest.call(this, 'GET', endpoint);
+
+				for (const webhook of webhooks) {
+					if (webhook.url === webhookUrl) {
+						webhookData.webhookId = webhook.id;
+						return true;
+					}
+				}
+
+				return false;
+			},
+			async create(this: IHookFunctions): Promise<boolean> {
+				const webhookUrl = this.getNodeWebhookUrl('default');
+
+				const formId = this.getNodeParameter('formId') as string;
+
+				const endpoint = `form/${formId}/webhook.json`;
+
+				// TODO: Add handshake key support
+				const body = {
+					url: webhookUrl,
+					standardize_field_values: true,
+					include_field_type: true,
+					content_type: 'json',
+				};
+
+				const response = await apiRequest.call(this, 'POST', endpoint, body);
+
+				const webhookData = this.getWorkflowStaticData('node');
+				webhookData.webhookId = response.id;
+				return true;
+			},
+			async delete(this: IHookFunctions): Promise<boolean> {
+				const webhookData = this.getWorkflowStaticData('node');
+
+				if (webhookData.webhookId !== undefined) {
+					const endpoint = `webhook/${webhookData.webhookId}.json`;
+
+					try {
+						const body = {};
+						await apiRequest.call(this, 'DELETE', endpoint, body);
+					} catch (e) {
+						return false;
+					}
+					// Remove from the static workflow data so that it is clear
+					// that no webhooks are registred anymore
+					delete webhookData.webhookId;
+				}
+
+				return true;
+			},
+		},
+	};
+
+	// @ts-ignore
+	async webhook(this: IWebhookFunctions): Promise<IWebhookResponseData> {
+		const bodyData = (this.getBodyData() as unknown) as IFormstackWebhookResponseBody;
+		const simple = this.getNodeParameter('simple') as string;
+
+		const response = bodyData as unknown as IDataObject;
+
+		if (simple) {
+			for (const key of Object.keys(response)) {
+				if ((response[key] as IDataObject).hasOwnProperty('value')) {
+					response[key] = (response[key] as IDataObject).value;
+				}
+			}
+		}
+
+		return {
+			workflowData: [
+				this.helpers.returnJsonArray([response as unknown as IDataObject]),
+			],
+		};
+	}
+}

packages/nodes-base/nodes/Formstack/GenericFunctions.ts

@@ -0,0 +1,206 @@
+import {
+	IExecuteFunctions,
+	IHookFunctions,
+	ILoadOptionsFunctions,
+	IWebhookFunctions,
+} from 'n8n-core';
+
+import {
+	IDataObject,
+	INodePropertyOptions,
+	NodeApiError,
+} from 'n8n-workflow';
+
+import {
+	OptionsWithUri,
+} from 'request';
+
+export interface IFormstackFieldDefinitionType {
+	id: string;
+	label: string;
+	description: string;
+	name: string;
+	type: string;
+	options: unknown;
+	required: string;
+	uniq: string;
+	hidden: string;
+	readonly: string;
+	colspan: string;
+	label_position: string;
+	num_columns: string;
+	date_format: string;
+	time_format: string;
+}
+
+export interface IFormstackWebhookResponseBody {
+	FormID: string;
+	UniqueID: string;
+}
+
+export interface IFormstackSubmissionFieldContainer {
+	field: string;
+	value: string;
+}
+
+export enum FormstackFieldFormat {
+	ID = 'id',
+	Label = 'label',
+	Name = 'name',
+}
+
+/**
+ * Make an API request to Formstack
+ *
+ * @param {IHookFunctions} this
+ * @param {string} method
+ * @param {string} url
+ * @param {object} body
+ * @returns {Promise<any>}
+ */
+export async function apiRequest(this: IHookFunctions | IExecuteFunctions | ILoadOptionsFunctions | IWebhookFunctions, method: string, endpoint: string, body: IDataObject = {}, query: IDataObject = {}): Promise<any> { // tslint:disable-line:no-any
+	const authenticationMethod = this.getNodeParameter('authentication', 0);
+
+	const options: OptionsWithUri = {
+		headers: {},
+		method,
+		body,
+		qs: query || {},
+		uri: `https://www.formstack.com/api/v2/${endpoint}`,
+		json: true,
+	};
+
+	if (!Object.keys(body).length) {
+		delete options.body;
+	}
+
+	try {
+		if (authenticationMethod === 'accessToken') {
+			const credentials = await this.getCredentials('formstackApi') as IDataObject;
+
+			if (credentials === undefined) {
+				throw new Error('No credentials got returned!');
+			}
+
+			options.headers!['Authorization'] = `Bearer ${credentials.accessToken}`;
+			return await this.helpers.request!(options);
+		} else {
+			return await this.helpers.requestOAuth2!.call(this, 'formstackOAuth2Api', options);
+		}
+	} catch (error) {
+		throw new NodeApiError(this.getNode(), error);
+	}
+}
+
+
+/**
+ * Make an API request to paginated Formstack endpoint
+ * and return all results
+ *
+ * @export
+ * @param {(IHookFunctions | IExecuteFunctions)} this
+ * @param {string} method
+ * @param {string} endpoint
+ * @param {IDataObject} body
+ * @param {IDataObject} [query]
+ * @returns {Promise<any>}
+ */
+export async function apiRequestAllItems(this: IHookFunctions | IExecuteFunctions | ILoadOptionsFunctions | IWebhookFunctions, method: string, endpoint: string, body: IDataObject, dataKey: string, query?: IDataObject): Promise<any> { // tslint:disable-line:no-any
+
+	if (query === undefined) {
+		query = {};
+	}
+
+	query.per_page = 200;
+	query.page = 0;
+
+	const returnData = {
+		items: [] as IDataObject[],
+	};
+
+	let responseData;
+
+	do {
+		query.page += 1;
+
+		responseData = await apiRequest.call(this, method, endpoint, body, query);
+		returnData.items.push.apply(returnData.items, responseData[dataKey]);
+	} while (
+		responseData.total !== undefined &&
+		Math.ceil(responseData.total / query.per_page) > query.page
+	);
+
+	return returnData;
+}
+
+
+/**
+ * Returns all the available forms
+ *
+ * @export
+ * @param {ILoadOptionsFunctions} this
+ * @returns {Promise<INodePropertyOptions[]>}
+ */
+export async function getForms(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]> {
+	const endpoint = 'form.json';
+	const responseData = await apiRequestAllItems.call(this, 'GET', endpoint, {}, 'forms', { folders: false });
+
+	if (responseData.items === undefined) {
+		throw new Error('No data got returned');
+	}
+	const returnData: INodePropertyOptions[] = [];
+	for (const baseData of responseData.items) {
+		returnData.push({
+			name: baseData.name,
+			value: baseData.id,
+		});
+	}
+	return returnData;
+}
+
+
+/**
+ * Returns all the fields of a form
+ *
+ * @export
+ * @param {ILoadOptionsFunctions} this
+ * @param {string} formID
+ * @returns {Promise<IFormstackFieldDefinitionType[]>}
+ */
+export async function getFields(this: IWebhookFunctions, formID: string): Promise<Record<string, IFormstackFieldDefinitionType>> {
+	const endpoint = `form/${formID}.json`;
+	const responseData = await apiRequestAllItems.call(this, 'GET', endpoint, {}, 'fields');
+
+	if (responseData.items === undefined) {
+		throw new Error('No form fields meta data got returned');
+	}
+
+	const fields = responseData.items as IFormstackFieldDefinitionType[];
+	const fieldMap: Record<string, IFormstackFieldDefinitionType> = {};
+
+	fields.forEach(field => {
+		fieldMap[field.id] = field;
+	});
+
+	return fieldMap;
+}
+
+
+/**
+ * Returns all the fields of a form
+ *
+ * @export
+ * @param {ILoadOptionsFunctions} this
+ * @param {string} uniqueId
+ * @returns {Promise<IFormstackFieldDefinitionType[]>}
+ */
+export async function getSubmission(this: ILoadOptionsFunctions | IWebhookFunctions, uniqueId: string): Promise<IFormstackSubmissionFieldContainer[]> {
+	const endpoint = `submission/${uniqueId}.json`;
+	const responseData = await apiRequestAllItems.call(this, 'GET', endpoint, {}, 'data');
+
+	if (responseData.items === undefined) {
+		throw new Error('No form fields meta data got returned');
+	}
+
+	return responseData.items as IFormstackSubmissionFieldContainer[];
+}

packages/nodes-base/nodes/Formstack/formstack.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 65.006 55.006" fill="#fff" fill-rule="evenodd" stroke="#000" stroke-linecap="round" stroke-linejoin="round"><use xlink:href="#A" x=".503" y=".503"/><symbol id="A" overflow="visible"><g stroke="none"><path d="M50.667 5.333h3.723a1.6 1.6 0 0 1 1.6 1.6V46.38a1.6 1.6 0 0 1-1.6 1.6h-3.723zm8 5.333h3.723a1.6 1.6 0 0 1 1.6 1.6v28.78a1.6 1.6 0 0 1-1.6 1.61h-3.723zM0 1.6C0 .714.714 0 1.6 0h44.8c.886 0 1.6.714 1.6 1.6v50.133c0 .886-.714 1.6-1.6 1.6H1.6c-.886 0-1.6-.714-1.6-1.6z" fill="#21b573" fill-rule="nonzero"/><path d="M11.2 8.533h24.624c.227 0 .428.143.503.357s.007.452-.17.593L11.533 29.182c-.16.128-.379.153-.564.064s-.302-.276-.302-.481V9.056c0-.295.239-.533.533-.533zm-.533 32.024v-8.252c0-.164.075-.319.204-.42l7.173-5.63c.094-.074.21-.114.329-.114h13.036c.234 0 .44.152.509.375s-.015.466-.208.598L11.502 40.996c-.163.112-.375.124-.55.032s-.285-.274-.285-.472zm.228 3.095l7.467-5.203c.163-.114.376-.127.552-.035s.287.274.287.473v5.42c0 .295-.239.533-.533.533H11.17c-.136 0-.267-.054-.364-.15s-.151-.228-.15-.364v-.236c0-.175.085-.338.228-.438z" fill-rule="nonzero"/></g></symbol></svg>

packages/nodes-base/nodes/Typeform/GenericFunctions.ts

@@ -115,6 +115,12 @@ export async function apiRequestAllItems(this: IHookFunctions | IExecuteFunction
 
 		responseData = await apiRequest.call(this, method, endpoint, body, query);
 
+		console.log({
+			endpoint,
+			method,
+			responseData,
+		});
+
 		returnData.items.push.apply(returnData.items, responseData.items);
 	} while (
 		responseData.page_count !== undefined &&

packages/nodes-base/package.json

@@ -89,6 +89,8 @@
       "dist/credentials/FreshworksCrmApi.credentials.js",
       "dist/credentials/FileMaker.credentials.js",
       "dist/credentials/FlowApi.credentials.js",
+      "dist/credentials/FormstackApi.credentials.js",
+      "dist/credentials/FormstackOAuth2Api.credentials.js",
       "dist/credentials/Ftp.credentials.js",
       "dist/credentials/FormIoApi.credentials.js",
       "dist/credentials/GetResponseApi.credentials.js",
@@ -386,6 +388,7 @@
       "dist/nodes/FormIo/FormIoTrigger.node.js",
       "dist/nodes/Flow/Flow.node.js",
       "dist/nodes/Flow/FlowTrigger.node.js",
+      "dist/nodes/Formstack/FormstackTrigger.node.js",
       "dist/nodes/Function.node.js",
       "dist/nodes/FunctionItem.node.js",
       "dist/nodes/GetResponse/GetResponse.node.js",