Hierarchy

  • default
    • Forms

Constructors

  • Example

    const OneBlink = require('@oneblink/sdk')

    const options = {
    accessKey: '123455678901ABCDEFGHIJKL',
    secretKey: '123455678901ABCDEFGHIJKL123455678901ABCDEFGHIJKL',
    }
    const forms = new OneBlink.Forms(options)

    Parameters

    Returns Forms

Properties

validateEndpointConfiguration: ((data) => {
    error: Joi.ValidationError;
    success: false;
} | {
    data: FormServerValidation;
    success: true;
}) = validateEndpointConfiguration

A static method available on the forms class, used for validating a api request configuration.

Example

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

Type declaration

    • (data): {
          error: Joi.ValidationError;
          success: false;
      } | {
          data: FormServerValidation;
          success: true;
      }
    • A static method available on the forms class, used for validating a api request configuration.

      Example

      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

      Parameters

      • data: unknown

      Returns {
          error: Joi.ValidationError;
          success: false;
      } | {
          data: FormServerValidation;
          success: true;
      }

Methods

  • Example

    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
    })

    Parameters

    • newForm: NewForm

      The form object to create.

    Returns Promise<Form>

  • Example

    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',
    })
    }

    Parameters

    • __namedParameters: {
          body: string | Buffer | Readable;
          contentType: string;
          fileName: string;
          formId: number;
          isPrivate: boolean;
          username?: string;
      }
      • body: string | Buffer | Readable

        The attachment's file content to upload

      • contentType: string

        The attachment's content type

      • fileName: string

        The attachment's file name

      • formId: number

        The exact id of the form the attachment will be uploaded for

      • isPrivate: boolean

        Determine if this attachment can be downloaded anonymously (false) or not (true)

      • Optional username?: string

        An optional username to allow a single user to download he attachment file

    Returns Promise<FormSubmissionAttachment>

  • Example

    const formId = 1
    forms
    .deleteForm(formId, true)
    .then(() => {
    // Form is not deleted
    })
    .catch((error) => {
    // Handle error here
    })

    Parameters

    • formId: number

      Id of the form.

    • Optional overrideLock: boolean

      Defaults to false. Set to true to force deleting of the form if the form is locked via the form builder

    Returns Promise<void>

  • Example

    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...
    })

    Parameters

    • parameters: {
          expiryInSeconds?: number;
          externalId?: string;
          formId: number;
          formsAppId?: number;
          preFillData?: Record<string, unknown>;
          previousFormSubmissionApprovalId?: string;
          secret?: string;
          username?: string;
      }

      An object containing all parameters to be passed to the function

      • Optional expiryInSeconds?: number

        The time in seconds until the generated form URL is no longer valid. This is set to 28800 seconds (8 hours) by default.

      • Optional externalId?: string

        The 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

      • formId: number

        The exact id of the form you wish to generate a URL for

      • Optional formsAppId?: number

        The 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 preFillData?: Record<string, unknown>

        An object with the form field names as keys and the prefill data as the values

      • Optional previousFormSubmissionApprovalId?: string

        The exact id of the previous form submission approval this submission will be associated to

      • Optional secret?: string

        A secret used to encrypt the username property which can be validated in a webhook.

      • Optional username?: string

        An 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.

    Returns Promise<{
        expiry: string;
        formUrl: string;
    }>

  • 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.

    Example

    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...
    })

    Parameters

    • formId: number

      The exact id of the form you wish to generate a URL for

    • attachmentId: string

      The attachment identifier from the form submission data

    • expiryInSeconds: number

      The number of seconds the signed URL should be valid for, must be greater than or equal to 900

    Returns Promise<{
        url: string;
    }>

    An absolute URL that that can be used to download the attachment

  • Example

    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...
    })

    Parameters

    • formId: number

      The exact id of the form you wish to generate a URL for

    • submissionId: string

      The submission identifier generated after a successful form submission, this will be return to you after a successful forms submission via a callback URL

    • expiryInSeconds: number

      The number of seconds the signed URL should be valid for, must be greater than or equal to 900

    Returns Promise<{
        url: string;
    }>

  • 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.

    Example

    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...
    })

    Parameters

    • options: {
          attachmentId: string;
          formId: number;
          submissionId: string;
      }

      The options required to generate a link

      • attachmentId: string

        The attachment identifier from the form submission data

      • formId: number

        The exact id of the form you wish to generate a URL for

      • submissionId: string

        The submission identifier for the the form submission

    Returns Promise<{
        url: string;
    }>

    An absolute URL that that can be used to download the attachment

  • Example

    const formId = 1
    const injectForms = false
    forms.getForm(formId, injectForms).then((form) => {
    // Use form here...
    })

    Parameters

    • formId: number

      The exact id of the form you wish to get

    • Optional injectForms: boolean

      Set to true to inject form elements from nested Form elements and Info Page elements.

    Returns Promise<Form>

  • Example

    const submissionId = 'f1eadc2b-79c8-4f97-8d92-cde64b34911f'
    forms
    .getFormSubmissionMeta(submissionId)
    .then(
    ({
    formSubmissionMeta,
    formApprovalFlowInstance,
    formSubmissionApprovals,
    formSubmissionPayments,
    }) => {
    // Use results here...
    },
    )

    Parameters

    • submissionId: string

      The exact id of the submission you wish to get the meta result for

    Returns Promise<FormSubmissionMetaResult>

  • Example

    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)
    }

    Parameters

    • formId: number

      The exact id of the form the attachment was uploaded on

    • attachmentId: string

      The attachment identifier from the form submission data

    Returns Promise<Buffer>

  • Example

    const formId = 1
    const attachmentId = 'c1f0f27b-4289-4ce5-9807-bf84971991aa'
    forms
    .getSubmissionAttachmentMeta(formId, attachmentId)
    .then((result) => {
    // Use result here
    })
    .catch((error) => {
    // Handle error here
    })

    Parameters

    • formId: number

      The exact id of the form the attachment was uploaded on

    • attachmentId: string

      The attachment identifier from the form submission data

    Returns Promise<HeadObjectOutput>

  • Example

    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()
    }

    Parameters

    • formId: number

      The exact id of the form the attachment was uploaded on

    • attachmentId: string

      The attachment identifier from the form submission data

    Returns Promise<ReadableStream>

  • Example

    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
    })

    Parameters

    • formId: number

      The exact id of the form you wish to get submission data for

    • submissionId: string

      The submission identifier generated after a successful form submission, this will be return to you after a successful forms submission via a callback URL

    • isDraft: boolean

      true if the submission is a draft submission, otherwise false

    Returns Promise<undefined | S3SubmissionData>

  • Example

    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
    })

    Parameters

    Returns Promise<Form>

  • Example

    const options = {
    isAuthenticated: true,
    name: 'Form Name',
    }
    forms
    .searchForms(options)
    .then((result) => {
    const forms = result.forms
    })
    .catch((error) => {
    // Handle error here
    })

    Parameters

    Returns Promise<FormsSearchResult>

  • 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

    Example

    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
    })

    Parameters

    Returns Promise<FormSubmissionHistorySearchResults>

  • Example

    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
    })

    Parameters

    • form: Form

      The form object to update

    • Optional overrideLock: boolean

      Defaults to false. Set to true to force updating of the form if the form is locked via the form builder

    Returns Promise<Form>

  • Upload a file to use as an attachment for an email based form workflow event.

    Example

    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],
    }
    }

    Parameters

    • options: {
          body: string | Buffer | Readable;
          contentType: string;
          filename: string;
      }

      Available options for uploading attachment.

      • body: string | Buffer | Readable

        The attachment's file content to upload

      • contentType: string

        The attachment's content type

      • filename: string

        The attachment's file name

    Returns Promise<{
        contentType: string;
        filename: string;
        s3: S3Configuration;
    }>

    The configuration required to add custom attachments to an email.

  • A static method available on the forms class for decrypting a user token. This token is passed to OneBlink webhooks in the userToken property.

    Parameters

    • details: {
          secret: string;
          userToken: string;
      }
      • secret: string

        The secret used to encrypt the username

      • userToken: string

        The user token to decrypt

    Returns string

    The decrypted username

  • A 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.

    Parameters

    • details: {
          secret: string;
          username: string;
      }
      • secret: string

        A string used to encrypt the username

      • username: string

        The username to encrypt

    Returns string

    The encrypted representation of the username

  • A 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.

    Example

    const element = {
    name: 'my test element',
    }

    const generatedElement = OneBlink.Forms.generateFormElement(element)

    return generatedElement

    Type Parameters

    Parameters

    • Optional formElementGenerationData: Record<string, unknown>

    Returns T

  • A 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.

    Example

    const childElement = Forms.generateFormElement({
    label: 'my first element',
    })

    const element = {
    name: 'my test element',
    elements: [childElement],
    }

    const generatedElement = OneBlink.Forms.generatePageElement(element)

    return generatedElement

    Parameters

    • Optional formElementGenerationData: Record<string, unknown>

    Returns PageElement

  • A static method available on the forms class, used for validating a OneBlink compatible Forms Definition.

    Example

    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

    Parameters

    • form: unknown

      The form object to validate.

    Returns {
        error: ValidationError;
        success: false;
    } | {
        data: NewForm;
        success: true;
    }

  • A static method available on the forms class, used for validating a OneBlink Form Event.

    Parameters

    • formElements: FormElement[]

      The form elements to validate against the event

    • data: unknown

      The untrusted data to validate

    Returns {
        error: ValidationError;
        success: false;
    } | {
        data: FormEvent;
        success: true;
    }

    A trusted form event