Class Forms

Hierarchy

default
- Forms

Constructors

constructor

new Forms(options): Forms

Parameters

options: ConstructorOptions

Returns Forms

Example

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

Properties

`Static`validateEndpointConfiguration

validateEndpointConfiguration: ((data: unknown) => {
    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.

Type declaration

- (data): {
      error: Joi.ValidationError;
      success: false;
  } | {
      data: FormServerValidation;
      success: true;
  }
- Parameters
  - data: unknown
  Returns {
      error: Joi.ValidationError;
      success: false;
  } | {
      data: FormServerValidation;
      success: true;
  }

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

Methods

createForm

createForm(newForm): Promise<Form>

Minimum Role Permission

Forms: Manager

Parameters

newForm: NewForm
The form object to create.

Returns Promise<Form>

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

createSubmissionAttachment

createSubmissionAttachment(attachment): Promise<FormSubmissionAttachment>

Minimum Role Permission

Upload Attachments: On

Parameters

attachment: {
    body: string | Buffer | Readable;
    contentType: string;
    fileName: string;
    formId: number;
    isPrivate: boolean;
    username?: string;
}
The attachment to upload
- 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)
- Optionalusername?: string
  An optional username to allow a single user to download he attachment file

Returns Promise<FormSubmissionAttachment>

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

deleteForm

deleteForm(formId, overrideLock?): Promise<void>
Minimum Role Permission

Forms: Manager
Parameters
- formId: number
  Id of the form.
- OptionaloverrideLock: 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 formId = 1
  forms
    .deleteForm(formId, true)
    .then(() => {
      // Form is deleted
    })
    .catch((error) => {
      // Handle error here
    })
```

executeWorkflowEvent

executeWorkflowEvent(params): Promise<void>

Minimum Role Permission

Submission Data: Manager

Parameters

params: {
    formId: number;
    submissionId: string;
    workflowEvent: FormWorkflowEvent;
}
An object containing all parameters to be passed to the function
- formId: number
  The form identifier for the workflow event you want to replay
- submissionId: string
  The submission identifier for the workflow event you want to replay
- workflowEvent: FormWorkflowEvent
  The configuration of the workflow event you want to replay

Returns Promise<void>

Example

const parameters = {
    formId: 1,
    submissionId: 'c1f0f27b-4289-4ce5-9807-bf84971991aa',
    workflowEvent: {
      type: 'PDF',
      configuration: {
        toEmail: ['{ELEMENT:Email}'],
        emailSubjectLine: 'Email Subject',
        excludedElementIds: [],
      },
    },
  }

  forms
    .executeWorkflowEvent(parameters)
    .then(() => {
      // Workflow event has been executed
    })
    .catch((error) => {
      // Handle error here
    })

generateFormUrl

generateFormUrl(parameters): Promise<{
expiry: string;
formUrl: string;
}>
App Association Required

Minimum Role Permission

Upload Form Prefill Data: Manager (only if using preFillData)
Parameters
- parameters: {
      expiryInSeconds?: number;
      externalId?: string;
      formId: number;
      formsAppId?: number;
      preFillData?: Record<string, unknown>;
      previousFormSubmissionApprovalId?: string;
      username?: string;
  }
  An object containing all parameters to be passed to the function
  - OptionalexpiryInSeconds?: number
    The time in seconds until the generated form URL is no longer valid. This is set to 28800 seconds (8 hours) by default.
  - OptionalexternalId?: 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
  - OptionalformsAppId?: 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.
  - OptionalpreFillData?: Record<string, unknown>
    An object with the form field names as keys and the prefill data as the values
  - OptionalpreviousFormSubmissionApprovalId?: string
    The exact id of the previous form submission approval this submission will be associated to
  - Optionalusername?: string
    An identifier for the user completing the form. Including this property will add the username to the access token. Use this if you would like to securely know the user that submitted the form in a webhook.
Returns Promise<{
expiry: string;
formUrl: string;
}>
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...
  })
```

generateSubmissionAttachmentUrl

generateSubmissionAttachmentUrl(formId, attachmentId, expiryInSeconds): Promise<{
url: 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.

Submission Data Key Supported

Key must be assigned to the form that the attachment was uploaded for.

Minimum Role Permission

Submission Data: Read Only
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 attachmentId = 'c1f0f27b-4289-4ce5-9807-bf84971991aa'
  const expiryInSeconds = 900
  forms
    .generateSubmissionAttachmentUrl(
      formId,
      attachmentId,
      expiryInSeconds,
    )
    .then((result) => {
      const attachmentUrl = result.url
      // Use URL here...
    })
```

generateSubmissionDataUrl

generateSubmissionDataUrl(formId, submissionId, expiryInSeconds): Promise<{
url: string;
}>
Submission Data Key Supported

Key must be assigned to the form that was submitted.

Minimum Role Permission

Submission Data: Read Only
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;
}>
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...
    })
```

generateWorkflowAttachmentLink

generateWorkflowAttachmentLink(options): 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.

Submission Data Key Supported

Key must be assigned to the form that the attachment was uploaded for.

Minimum Role Permission

Submission Data: Read Only
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 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...
    })
```

getForm

getForm(formId, injectForms?): Promise<Form>
Minimum Role Permission

Forms: Read Only
Parameters
- formId: number
  The exact id of the form you wish to get
- OptionalinjectForms: boolean
  Set to true to inject form elements from nested Form elements and Info Page elements.
Returns Promise<Form>
Example
```
const formId = 1
  const injectForms = false
  forms.getForm(formId, injectForms).then((form) => {
    // Use form here...
  })
```

getFormSubmissionMeta

getFormSubmissionMeta(submissionId): Promise<FormSubmissionMetaResult>

Submission Data Key Supported

Key must be assigned to the form that was submitted.

Minimum Role Permission

Submission Data: Read Only

Parameters

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

Returns Promise<FormSubmissionMetaResult>

Example

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

getSubmissionAttachmentBuffer

getSubmissionAttachmentBuffer(formId, attachmentId): Promise<Buffer>

Submission Data Key Supported

Key must be assigned to the form that the attachment was uploaded for.

Minimum Role Permission

Submission Data: Read Only

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

getSubmissionAttachmentMeta

getSubmissionAttachmentMeta(formId, attachmentId): Promise<HeadObjectOutput>
Submission Data Key Supported

Key must be assigned to the form that was submitted.

Minimum Role Permission

Submission Data: Read Only
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 formId = 1
  const attachmentId = 'c1f0f27b-4289-4ce5-9807-bf84971991aa'
  forms
    .getSubmissionAttachmentMeta(formId, attachmentId)
    .then((result) => {
      // Use result here
    })
    .catch((error) => {
      // Handle error here
    })
```

getSubmissionAttachmentStream

getSubmissionAttachmentStream(formId, attachmentId): Promise<ReadableStream>

Submission Data Key Supported

Key must be assigned to the form that the attachment was uploaded for.

Minimum Role Permission

Submission Data: Read Only

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

getSubmissionData

getSubmissionData(formId, submissionId, isDraft): Promise<undefined | S3SubmissionData>
Submission Data Key Supported

Key must be assigned to the form that was submitted.

Minimum Role Permission

Submission Data: Read Only
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
```
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
    })
```

migrateForm

migrateForm(migrationOptions): Promise<Form>

Minimum Role Permission

Forms: Manager

Parameters

migrationOptions: FormMigrationData
Migration options

Returns Promise<Form>

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,
        },
      ],
      approvalForms: [
        {
          stepLabel: 'Approve',
          targetFormId: 53,
        },
      ],
      versionId: 5,
    })
    .then((migratedForm) => {
      // do something with form
    })
    .catch((error) => {
      // Handle error here
    })

searchForms

searchForms(searchParams?): Promise<FormsSearchResult>

Minimum Role Permission

Forms: Read Only

Parameters

OptionalsearchParams: FormsSearchOptions
Search options.

Returns Promise<FormsSearchResult>

Example

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

searchSubmissions

searchSubmissions(options): Promise<FormSubmissionHistorySearchResults>

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

Submission Data Key Supported

Results will be restricted to forms that have been assigned to the Key.

Minimum Role Permission

Submission Data: Read Only

Parameters

options: FormSubmissionHistorySearchParameters
Search options.

Returns Promise<FormSubmissionHistorySearchResults>

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

updateForm

updateForm(form, overrideLock?): Promise<Form>

Minimum Role Permission

Forms: Manager

Parameters

form: Form
The form object to update
OptionaloverrideLock: 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>

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

uploadEmailAttachment

uploadEmailAttachment(options): Promise<{
    contentType: string;
    filename: string;
    s3: S3Configuration;
}>
Upload a file to use as an attachment for an email based form workflow event.

Minimum Role Permission

Upload Attachments: On
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.
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],
    }
  }
```

`Static`generateFormElement

generateFormElement<T>(formElementGenerationData?): T
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.
Type Parameters
- T extends _FormElementBase
Parameters
- OptionalformElementGenerationData: Record<string, unknown>
Returns T
Example
```
const element = {
    name: 'my test element',
  }

  const generatedElement = OneBlink.Forms.generateFormElement(element)

  return generatedElement
```

`Static`generatePageElement

generatePageElement(formElementGenerationData?): PageElement
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.
Parameters
- OptionalformElementGenerationData: Record<string, unknown>
Returns PageElement
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
```

`Static`validateForm

validateForm(form): {
    error: ValidationError;
    success: false;
} | {
    data: NewForm;
    success: true;
}

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

Parameters

form: unknown
The form object to validate.

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

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

`Static`validateFormEvent

validateFormEvent(formElements, data): {
    error: ValidationError;
    success: false;
} | {
    data: FormEvent;
    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

Class Forms

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Forms

Example

Properties

StaticvalidateEndpointConfiguration

Type declaration

Parameters

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

Example

Methods

createForm

Parameters

Returns Promise<Form>

Example

createSubmissionAttachment

Parameters

body: string | Buffer | Readable

contentType: string

fileName: string

formId: number

isPrivate: boolean

Optionalusername?: string

Returns Promise<FormSubmissionAttachment>

Example

deleteForm

Parameters

Returns Promise<void>

Example

executeWorkflowEvent

Parameters

formId: number

submissionId: string

workflowEvent: FormWorkflowEvent

Returns Promise<void>

Example

generateFormUrl

Parameters

OptionalexpiryInSeconds?: number

OptionalexternalId?: string

formId: number

OptionalformsAppId?: number

OptionalpreFillData?: Record<string, unknown>

OptionalpreviousFormSubmissionApprovalId?: string

Optionalusername?: string

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

Example

generateSubmissionAttachmentUrl

Parameters

Returns Promise<{ url: string; }>

Example

generateSubmissionDataUrl

Parameters

Returns Promise<{ url: string; }>

Example

generateWorkflowAttachmentLink

Parameters

attachmentId: string

formId: number

submissionId: string

Returns Promise<{ url: string; }>

Example

getForm

Parameters

Returns Promise<Form>

Example

getFormSubmissionMeta

Parameters

Returns Promise<FormSubmissionMetaResult>

Example

getSubmissionAttachmentBuffer

Parameters

Returns Promise<Buffer>

`Static`validateEndpointConfiguration

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

`Optional`username?: string

`Optional`expiryInSeconds?: number

`Optional`externalId?: string

`Optional`formsAppId?: number

`Optional`preFillData?: Record<string, unknown>

`Optional`previousFormSubmissionApprovalId?: string

`Optional`username?: string

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

Returns Promise<{
url: string;
}>

Returns Promise<{
url: string;
}>

Returns Promise<{
url: string;
}>

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

`Static`generateFormElement

`Static`generatePageElement

`Static`validateForm

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

`Static`validateFormEvent

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