Static
validateA static method available on the forms class, used for validating a api request configuration.
const endpointConfiguration = {
type: 'CALLBACK',
configuration: {
url: 'https://a-website.com/endpoint',
},
}
const result = OneBlink.Forms.validateEndpointConfiguration(
endpointConfiguration,
)
if (!result.success) {
throw result.error
}
const validatedEndpointConfiguration = result.data
return validatedEndpointConfiguration
A static method available on the forms class, used for validating a api request configuration.
const endpointConfiguration = {
type: 'CALLBACK',
configuration: {
url: 'https://a-website.com/endpoint',
},
}
const result = OneBlink.Forms.validateEndpointConfiguration(
endpointConfiguration,
)
if (!result.success) {
throw result.error
}
const validatedEndpointConfiguration = result.data
return validatedEndpointConfiguration
forms
.createForm({
name: 'testsform',
formsAppEnvironmentId: 1,
description: 'a form',
organisationId: '0101010101010',
formsAppEnvironmentId: 1,
elements: [],
isAuthenticated: false,
submissionEvents: [],
postSubmissionAction: 'FORMS_LIBRARY',
formsAppIds: [1, 2, 3],
})
.then((form) => {
// use form here
})
.catch((error) => {
// Handle error here
})
The form object to create.
const fs = require('fs')
const util = require('util')
const readFileAsync = util.promisify(fs.readFile)
async function run() {
const formId = 1
const imageFileName = 'profile-picture.png'
const imageBuffer = await readFileAsync(imageFileName)
const imageResult = await forms.createSubmissionAttachment({
formId,
body: imageBuffer,
isPrivate: false,
contentType: 'image/png',
fileName: imageFileName,
})
const documentFileName = 'secrets.text'
const readableStream = fs.createReadStream(documentFileName)
const documentResult = await forms.createSubmissionAttachment({
formId,
isPrivate: true,
contentType: 'text/plain',
fileName: documentFileName,
body: readableStream,
username: 'user@example.com',
})
}
The attachment's file content to upload
The attachment's content type
The attachment's file name
The exact id of the form the attachment will be uploaded for
Determine if this attachment can be downloaded anonymously (false
) or
not (true
)
Optional
username?: stringAn optional username to allow a single user to download he attachment file
const formId = 1
forms
.deleteForm(formId, true)
.then(() => {
// Form is not deleted
})
.catch((error) => {
// Handle error here
})
Id of the form.
Optional
overrideLock: booleanDefaults to false
. Set to true to force deleting of
the form if the form is locked via the form builder
const parameters = {
formId: 1,
formsAppId: 2,
externalId: 'My Custom Identifier',
preFillData: {
FieldName1: 'A Machine',
FieldName2: 'Room B',
},
expiryInSeconds: 36800,
username: 'username',
secret: 'sshh',
previousFormSubmissionApprovalId: 1,
}
forms.generateFormUrl(parameters).then((result) => {
const formUrl = result.formUrl
// Use form URL here...
})
An object containing all parameters to be passed to the function
Optional
expiryThe time in seconds until the generated form URL is no longer valid. This
is set to 28800
seconds (8 hours) by default.
Optional
externalThe external identifier of the form submission you wish to use, this identifier will be returned to you with the submissionId after a successful submission to allow you to retrieve the data later
The exact id of the form you wish to generate a URL for
Optional
formsThe exact id of the forms app you wish to generate a URL for. This is set to the first forms app the form was added to by default.
Optional
preAn object with the form field names as keys and the prefill data as the values
Optional
previousThe exact id of the previous form submission approval this submission will be associated to
Optional
secret?: stringA secret used to encrypt the username
property which can be validated
in a webhook.
Optional
username?: stringAn identifier for the user completing the form. Use this if you would like to securely know the user that submitted the form in a webhook.
Generate a url to download an attachment. The expiration of the URL is
determined by input parameters and only last a maximum of 12 hours. This
should be used for short lived URLs that will be used immediately. If you
require a URL that needs to last longer, consider using the
generateWorkflowAttachmentLink()
function.
const formId = 1
const attachmentId = 'c1f0f27b-4289-4ce5-9807-bf84971991aa'
const expiryInSeconds = 900
forms
.generateSubmissionAttachmentUrl(
formId,
attachmentId,
expiryInSeconds,
)
.then((result) => {
const attachmentUrl = result.url
// Use URL here...
})
The exact id of the form you wish to generate a URL for
The attachment identifier from the form submission data
The number of seconds the signed URL should be valid
for, must be greater than or equal to 900
An absolute URL that that can be used to download the attachment
const formId = 1
const submissionId = 'c1f0f27b-4289-4ce5-9807-bf84971991aa'
const expiryInSeconds = 900
forms
.generateSubmissionDataUrl(formId, submissionId, expiryInSeconds)
.then((result) => {
const submissionDataUrl = result.url
// Use URL here...
})
The exact id of the form you wish to generate a URL for
The submission identifier generated after a successful form submission, this will be return to you after a successful forms submission via a callback URL
The number of seconds the signed URL should be valid
for, must be greater than or equal to 900
Generate a workflow attachment link for an attachment. The expiration of
the link is configured for the account and cannot be changed for generated
links. If you require a URL that should be short lived, consider using the
generateSubmissionAttachmentUrl()
function.
const formId = 1
const attachmentId = 'c1f0f27b-4289-4ce5-9807-bf84971991aa'
const submissionId = '49ae3fa9-798d-467c-96e1-5c606fe42fbb'
forms
.generateWorkflowAttachmentLink({
formId,
attachmentId,
submissionId,
})
.then((result) => {
const attachmentUrl = result.url
// Use URL here...
})
The options required to generate a link
The attachment identifier from the form submission data
The exact id of the form you wish to generate a URL for
The submission identifier for the the form submission
An absolute URL that that can be used to download the attachment
const formId = 1
const injectForms = false
forms.getForm(formId, injectForms).then((form) => {
// Use form here...
})
The exact id of the form you wish to get
Optional
injectForms: booleanSet to true
to inject form elements from nested Form
elements and Info Page elements.
const submissionId = 'f1eadc2b-79c8-4f97-8d92-cde64b34911f'
forms
.getFormSubmissionMeta(submissionId)
.then(
({
formSubmissionMeta,
formApprovalFlowInstance,
formSubmissionApprovals,
formSubmissionPayments,
}) => {
// Use results here...
},
)
The exact id of the submission you wish to get the meta result for
const fs = require('fs')
const util = require('util')
const writeFileAsync = util.promisify(fs.writeFile)
async function run() {
const formId = 1
const attachmentId = 'c1f0f27b-4289-4ce5-9807-bf84971991aa'
const buffer = await forms.getSubmissionAttachmentBuffer(
formId,
attachmentId,
)
await writeFileAsync('file.png', buffer)
}
The exact id of the form the attachment was uploaded on
The attachment identifier from the form submission data
const formId = 1
const attachmentId = 'c1f0f27b-4289-4ce5-9807-bf84971991aa'
forms
.getSubmissionAttachmentMeta(formId, attachmentId)
.then((result) => {
// Use result here
})
.catch((error) => {
// Handle error here
})
The exact id of the form the attachment was uploaded on
The attachment identifier from the form submission data
const fs = require('fs')
const util = require('util')
const stream = require('stream')
const finishedAsync = util.promisify(stream.finished)
async function run() {
const formId = 1
const attachmentId = 'c1f0f27b-4289-4ce5-9807-bf84971991aa'
const readableStream = await forms.getSubmissionAttachmentStream(
formId,
attachmentId,
)
const writableStream = fs.createWriteStream('file.png')
readableStream.pipe(writableStream)
await finishedAsync(readableStream)
writableStream.end()
}
The exact id of the form the attachment was uploaded on
The attachment identifier from the form submission data
const formId = 1
const submissionId = 'c1f0f27b-4289-4ce5-9807-bf84971991aa'
const isDraft = false
forms
.getSubmissionData(formId, submissionId, isDraft)
.then((result) => {
const definition = result?.definition
const submission = result?.submission
})
.catch((error) => {
// Handle error here
})
The exact id of the form you wish to get submission data for
The submission identifier generated after a successful form submission, this will be return to you after a successful forms submission via a callback URL
true
if the submission is a draft submission, otherwise
false
forms
.migrateForm({
formsAppEnvironmentId: 2,
sourceFormId: 123,
targetFormId: 234,
elements: true,
approvalSteps: false,
submissionEvents: false,
tags: true,
approvalSteps: false,
serverValidation: false,
externalIdGenerationOnSubmit: false,
personalisation: false,
postSubmissionAction: false,
embeddedForms: [
{
sourceElementId: 'acbd',
targetFormId: 678,
},
],
versionId: 5,
})
.then((migratedForm) => {
// do something with form
})
.catch((error) => {
// Handle error here
})
Migration options
const options = {
isAuthenticated: true,
name: 'Form Name',
}
forms
.searchForms(options)
.then((result) => {
const forms = result.forms
})
.catch((error) => {
// Handle error here
})
Optional
searchParams: FormsSearchOptionsSearch options.
Search for details on submissions that match the search parameters. Then use the information to fetch the actual submission data, if it is still available
const options = {
formId: 1,
submissionDateFrom: '2018-08-16T05:28:26.448Z',
submissionDateTo: '2019-08-16T05:28:26.448Z',
isValid: true,
submissionTitle: 'Smith',
}
forms
.searchSubmissions(options)
.then((result) => {
const submissionDetails = result.formSubmissionMeta
return Promise.all(
submissionDetails.map((metaData) =>
forms.getSubmissionData(
metaData.formId,
metaData.submissionId,
),
),
)
})
.then((submissions) => {
// something...
})
.catch((error) => {
// Handle error here
})
Search options.
forms
.updateForm(
{
id: 1,
name: 'testsform',
formsAppEnvironmentId: 1,
description: 'a form',
organisationId: '0101010101010',
formsAppEnvironmentId: 1,
elements: [],
isAuthenticated: false,
submissionEvents: [],
postSubmissionAction: 'FORMS_LIBRARY',
formsAppIds: [1, 2, 3],
},
true,
)
.then((form) => {
// use form here
})
.catch((error) => {
// Handle error here
})
The form object to update
Optional
overrideLock: booleanDefaults to false
. Set to true to force updating of
the form if the form is locked via the form builder
Upload a file to use as an attachment for an email based form workflow event.
export async function post(request) {
const readableStream = fs.createReadStream(documentFileName)
const emailAttachment = await forms.uploadEmailAttachment({
filename: 'document.text',
contentType: 'text/plain',
body: readableStream,
})
return {
attachments: [emailAttachment],
}
}
Available options for uploading attachment.
The attachment's file content to upload
The attachment's content type
The attachment's file name
The configuration required to add custom attachments to an email.
Static
decryptA static method available on the forms class for decrypting a user token.
This token is passed to OneBlink webhooks in the userToken
property.
The secret used to encrypt the username
The user token to decrypt
The decrypted username
Static
encryptA static method available on the forms class for securely encrypting a user
identifier (e.g. email address) when the OneBlink API is being called with
a FaaS key and not a user JWT. This is automatically done for the user in
generateFormUrl()
by passing the username
and
secret
options.
A string used to encrypt the username
The username to encrypt
The encrypted representation of the username
Static
generateA static method available on the forms class, used for both creating and validating a OneBlink Form Element.
The method will set reasonable defaults for any values not passed to it, and validate ones that are against our Element Schema.
const element = {
name: 'my test element',
}
const generatedElement = OneBlink.Forms.generateFormElement(element)
return generatedElement
Optional
formElementGenerationData: Record<string, unknown>Static
generateA static method available on the forms class, used for both creating and validating a OneBlink Page Element.
The method will set reasonable defaults for any values not passed to it, and validate ones that are against our Element Schema.
const childElement = Forms.generateFormElement({
label: 'my first element',
})
const element = {
name: 'my test element',
elements: [childElement],
}
const generatedElement = OneBlink.Forms.generatePageElement(element)
return generatedElement
Optional
formElementGenerationData: Record<string, unknown>Static
validateA static method available on the forms class, used for validating a OneBlink compatible Forms Definition.
const form = {
id: 1,
name: 'testsform',
formsAppEnvironmentId: 1,
description: 'a form',
organisationId: '0101010101010',
elements: [],
isAuthenticated: false,
submissionEvents: [],
postSubmissionAction: 'FORMS_LIBRARY',
formsAppIds: [1, 2, 3],
}
const result = OneBlink.Forms.validateForm(form)
if (!result.success) {
throw result.error
}
const validatedNewForm = result.data
return validatedNewForm
The form object to validate.
Static
validateA static method available on the forms class, used for validating a OneBlink Form Event.
The form elements to validate against the event
The untrusted data to validate
A trusted form event
Example