HomeGuidesRecipesAPI
HomeGuidesAPILog In

Writable Data Objects

πŸ“˜

This article targets concepts for record maintenance of an established connection to a writable data object, see the Data Connections page for generic concepts and instructions on how to establish such data connections.

Writable data objects use a SmartIQ type connection with custom data objects to provide two way data access where records can be selected, added, edited or even deleted from a data connection.

Writable Data Object connections are available in Design under Writable Data Objects, and can be dropped onto the finish page. As such this feature is only usable in projects with a finish page.

Once added to a project the placeholders relating to the data objects will be available for use.

πŸ“˜

To show data from data objects the data question should be used.

The Writable Data Object can't be used to show data.

Usage

There are two core implementation methods for records within a writable data object;
In the background, upon a workflow transition or the completion of an entire workflow, without user knowledge;
or during an in progress form where the user indicates they wish to add edit or delete an existing record, where a targeted user interface (a data modal) is displayed to the user.

The correct method will depend on the business process being delivered. If the form collects the data to create or add or edit a record, the background submission method is appropriate. Whereas if the record needs to be selected during form interaction, users will need the ability to add/edit records on an ad-hoc basis. Often the techniques are used in conjunction with each other. For example 'Form A' might create a client record that are available for selection and maintenance in 'Form B'. As depicted in the screen shots below.

Writable Data Object Type Considerations

Beyond, basic examples such as mapping a date field to a to a question that captures currency will cause an error there are some finer details that should be noted when designing question sets for writable data objects.

Data TypeAppropriate Form QuestionsSpecial Considerations
TextCan be mapped to virtually any question, however typically mapped to a plain text or rich text box.
Can also be mapped to a multiple choice question, where the answer's selected value will be stored.
Mapped to Rich Text - Data captured will be in HTML format.
Mapped to multiple choice question where multiple items can be selected - the selection(s) will be saved as a pipe separated values (for example "blue|green|red")
Mapping to Data Question - The selected record's unique field should be saved. Where the data question allows multiple select the unique fields will be separated by a pipe as per multiple choice above.
DateText box with a date display type.
NumberNumeric Question or Text Question formatted to number or currency.When formatted to currency the currency symbol will be removed before storing the data.
File (Binary)File Upload QuestionFile Uploads require two components, the binary data of the uploaded file and its filename. Note the filename contains the file's extensions which determines how to open the file.
Boolean (True/False)Multiple Choice, display type check box.Writable data objects mapped to multiple choice questions have two behaviour options:
- write selected value
- write checked
Typically with write "selected values" selected a yes no style question is being referenced and should pass the term "true" or "false" to the data connection depending on the answer selected. Whereas for a check box styled question where each answer can be checked or unchecked individually the write checked behaviour is typically used.

Data Store

Updating writable data upon submission occurs in the background most likely without the user knowing. Individual writes can occur upon the completion of a workflow state or at the end of an entire workflow.
Configuration involves mapping the writable data objects field's (via placeholders) to appropriate questions in the question set.

Placeholder and Override Write Behavior

On execution (either via generation, for Data Stores with a "Write On" set in their properties, or via the Override action) the data store will attempt to update all columns in the linked table.

The value passed will be:

  • the value specified in the Override action, if any
  • otherwise, the value of the form question mapped via placeholder, if any
  • otherwise, NULL

Note: this means that attempting to update only a small number of fields on an existing with an Override action will cause any fields which are not mapped to a placeholder or specified in the action inputs, to be set to NULL in the database. If this is not the desired behavior, the columns should either be mapped as placeholders or specified as inputs on the Override action.

Workflow Write Considerations and Configuration

πŸ“˜

For non-workflow forms, data stores are written on form submission.

For forms that contain workflow, a 'Write On' drop-down will appear on the data store's properties panel, defaulting to "All transitions". A decision can be made as to whether to:

  • Commit the data on all workflow transitions
  • Commit the data only at the conclusion of the workflow
  • Do not commit the data automatically

In the second and third cases, the Writable Data Object Override action is used to manually commit data on a per-workflow-transition basis as desired.

πŸ“˜

Object persistence

By default (using Write On All Transitions) the Data Store will attempt to maintain and update a single data record for a workflow. If multiple records need to be created within a single workflow, the Writable Data Object Override action must be used and the ObjectID field should be overridden with a new value.

Repeating Writable Data Objects

Writable data objects can be driven by repeating pages or sections so that an individual record is created for each instance of the repeat. For workflow projects that write on each or more than one workflow transition the initial write will create the records whereas the subsequent writes will edit them including the delete.

🚧

Repeat Sources

Repeating Writable Data Objects cannot be driven by a repeating data source. I.e. must be driven by a repeating section.

Use the Repeat checkbox and select an appropriate source to configure a submission data object as repeating.

Data Modal

Data modals open a dialog to add, edit or delete records from a Data Connection independent from the in progress form. Changes are committed immediately upon saving.

To configure the in form data writes, two core steps need to occur:

  1. Create a Writable Data Object with Read/Write Access that can be used across multiple forms.

  1. Configure your form to call upon the data modal where appropriate.