Writable Data Objects
Writable Data Objects only offer record maintenance through already established Data Connections
Writable Data Objects are not intended as an intermediary for data flow between multiple external systems
See Data Connection for generic concepts or connection set-up information
Writable data objects provide two way data access where records can be selected, added, edited or even deleted from a data connection. This is intended as a way for records to be shared between different forms, or across different states of a workflow. Data stored within SmartIQ is not available for reference from external systems (excluding where Custom Data Objects are externally managed); if external reference is required, data should be stored externally.
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
Writable Data Objects automatically find and list Data Objects that have their Access set to read/write permissions. Primarily these will be SmartIQ type connection with custom data objects, or SQL Server and PostgreSQL connections.
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 Type | Appropriate Form Questions | Special Considerations |
|---|---|---|
| Text | Can 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. |
| Date | Text box with a date display type. | |
| Number | Numeric 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 Question | File 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:
- Create a Writable Data Object with Read/Write Access that can be used across multiple forms.
- Configure your form to call upon the data modal where appropriate.
Updated about 2 months ago