Import module

📖 Description

The Import module contains helper functions for importing data into forms. This is useful for prefilling forms.

tip

Read the Prefilling forms guide for more information.

📇 Functions overview

The following table shows the available data import functions and a description of what they do:

Function	Description
fields	Imports data into the form fields. This is the de facto function for importing data into a form.
CSV	Import data into a form using CSV input.
values	Import raw data values into the form.

👩‍💻 Example

import { run } from "@tripetto/runner-autoscroll";
import { Import } from "@tripetto/runner";

run({
  definition: /* Supply your form definition here */,
  onImport: (instance) => {
    // This example assumes the form has two text fields with
    // the data identifiers (aliases) `FIRSTNAME` and `LASTNAME`.
    Import.fields(instance, [
      {
        name: "FIRSTNAME",
        value: "John",
      },
      {
        name: "LASTNAME",
        value: "Doe",
      }
    ]);

    // Or use the generated key of each field
    Import.fields(instance, [
      {
        key: "9ef64ab160ef6096ceecb4561f3eecc37007b669337929393a9d3789fa744f3e",
        value: "John",
      },
      {
        key: "e14599867b9fd518459e7ecaf974d33f84f2c3b322f644e838f948c2136eec3a",
        value: "Doe",
      }
    ]);
  }
});

▶️ Functions

---

🔧 CSV

Imports data values using a CSV record. The number of columns in the CSV record and their order should exactly match the number of fields and their order in the instance.

Signature

CSV(
  instanceOrContext: Instance | Context,
  record: string,
  selection?: string[],
  delimiter?: string
): boolean

Parameters

Name	Type	Optional	Description
instanceOrContext	Instance | Context	No	Reference to the instance or context.
record	string	No	Specifies the CSV record string to import.
selection	string[]	Yes	Specifies the identifiers of the slots that should be imported.
delimiter	string	Yes	Specifies the delimiter for the CSV input (default is ,).

Return value

Returns true if the import succeeded or false when the import failed (probably because the column and field count are not equal).

tip

You can use the CSV export function to retrieve a sample CSV record for a form definition.

---

🔧 fields

Import data fields to the supplied form instance. You can import the fields by referencing the unique key of the field or by specifying the name of the field.

Signature

fields(
  instanceOrContext: Instance | Context,
  fields: (IFieldByKey | IFieldByName)[],
  selection?: string[],
  separator?: string
): boolean

Parameters

Name	Type	Optional	Description
instanceOrContext	Instance | Context	No	Reference to the instance or context.
fields	(IFieldByKey | IFieldByName)[]	No	Contains the fields to import. You can reference a field by its key or field name.
selection	string[]	Yes	Specifies the identifiers of the slots that should be imported.
separator	string	Yes	Specifies the string that is used to separate subject and field names for slots that are part of an iteration (default is /).

Return value

Returns true if the import succeeded or false when there was an error and one or more of the specified fields could not be imported.

Example

import { run } from "@tripetto/runner-autoscroll";
import { Import } from "@tripetto/runner";

run({
  definition: /* Supply your form definition here */,
  onImport: (instance) => {
    // This example assumes the form has two text fields with
    // the data identifiers (aliases) `FIRSTNAME` and `LASTNAME`.
    Import.fields(instance, [
      {
        name: "FIRSTNAME",
        value: "John",
      },
      {
        name: "LASTNAME",
        value: "Doe",
      }
    ]);

    // Or use the generated key of each field
    Import.fields(instance, [
      {
        key: "9ef64ab160ef6096ceecb4561f3eecc37007b669337929393a9d3789fa744f3e",
        value: "John",
      },
      {
        key: "e14599867b9fd518459e7ecaf974d33f84f2c3b322f644e838f948c2136eec3a",
        value: "Doe",
      }
    ]);
  }
});

---

🔧 values

Import data values to the instance.

Signature

values(instanceOrContext: Instance | Context, values: IValues, selection?: string[]): boolean

Parameters

Name	Type	Optional	Description
instanceOrContext	Instance | Context	No	Reference to the instance or context.
values	IValues	No	Specifies the values to import.
selection	string[]	Yes	Specifies the identifiers of the slots that should be imported.

Return value

Returns true if the import succeeded or false when there was an error and one or more of the specified fields could not be imported.

⛓️ Interfaces

---

🔗 IFieldByKey

Describes the interface to import data using the fields function where the fields are referenced by their keys (unique identifiers).

Type declaration

interface IFieldByKey {
  key: string;
  value: any;
  reference?: string;Optional
  time?: number;Optional
}

🖱️ Hover with the mouse over a property name for a tooltip with the description of that property. Click it for more information.

---

🏷️ key

Key of the field.

Type

string

---

🏷️ reference

Contains the data reference.

Type

string

---

🏷️ time

Contains the UTC set time of the data.

Type

number

---

🏷️ value

Contains the data value.

Type

any

---

🔗 IFieldByName

Describes the interface to import data using the fields function where the fields are referenced by their names.

Type declaration

interface IFieldByName {
  name: string;
  value: any;
  reference?: string;Optional
  time?: number;Optional
}

🖱️ Hover with the mouse over a property name for a tooltip with the description of that property. Click it for more information.

---

🏷️ name

Contains the name of the field.

Type

string

---

🏷️ reference

Contains the data reference.

Type

string

---

🏷️ time

Contains the UTC set time of the data.

Type

number

---

🏷️ value

Contains the data value.

Type

any

---

🔗 IValues

Describes the interface to import data using the values function.

Type declaration

interface IValues {
  /* Specifies the slot identifier. */
  [slot: string]: {
    values: {
      /*
       * The keys for the contextual values are composed using the condition hashes of the
       * context. If the context is global the key of that value is `*`. If the
       * context is defined by a single condition, the key is the computed
       * hash of the stringified condition data (where the `id` property is set to
       * an empty `string`). If the context is defined by 2 or more conditions, the
       * computed hashes of these conditions are used to calculate a new hash. The
       * computed condition hashes are concatenated in chronological order and then a
       * `SHA2_256` hash is generated for this concatenated string. This hash is
       * used as key.
       */
      [context: string]: {
        /* Contains the value to import. */
        value: any;

        /* Contains the optional reference. */
        reference?: string;

        /* Contains the optional UTC set time of the value. */
        time?: number;
      };
    };
  };
}

info

This interface is basically a partial implementation of the IValues interface in the export module. This means you can use the object returned by the values export function as input for the values import function.