Overview

This article provides guidance on how to use the Write to Data Store Entity smart service in the process modeler. The Write to Data Store Entity smart service is a powerful tool that allows you to easily insert or update data in your database from Appian.

The Write to Data Store Entity Smart Service adds process data to an entity in a Data Store. It allows you to select a single entity in a data store to save or update data.

You must create a node input with the same custom data type (CDT) as the entity in the data store that you select. The way you define your custom data type determines whether you can update existing records in the data store. You must also designate a field in the CDT as your record ID (primary key) and specify an existing value, or the data written is always inserted as a new record.

When the activity is attended, you can select the element or subelement of a custom data type to store form-data in your configuration of the interface. Data written to a data store using this activity must be supported in the XML 1.0 standard.

Note: Unicode control characters – such as characters #x0 and #x1 through #x1F – are not fully supported in XML 1.0.

Any update on related data is based on the JPA annotations/DB schema defined for the entity. For example, updating the parent in a one-to-many containment relationship also affects the children, but updating one side of a lookup relationship will not affect the related object.

Also note that any CDT created through the Data Type Designer or uploaded via an XSD file has the cascade attribute set to ALL on the child CDT by default, so unless you have manually changed this setting, updating a parent CDT value with this setting also affects the child value.

See also: CDT Relationships

Permissions Needed

The user executing this activity must have Viewer rights to the selected data store, in order to update or insert information.

NOTE: Since the Write to Data Store Entity Smart Service works directly with your data store and custom data types, be sure to note the Schema Design Best Practices before implementing this smart service.

Properties

• Category: Data Services (Integration Services)

• Icon:

• Assignment Options - Attended

See also: Smart Services

Configuration Options

This section contains tab configuration details specific to this smart service. For more information about common configurations see the Process Node Properties page.

Data Tab

Node Inputs

See also: Data Store Entity

Updating an Existing Value

The data that you write can update an existing record when a primary key is properly configured for the entity and provided by your node input.

Saving a New Value

Saving a new value for an existing record does not merge the records, the old record is overwritten.

For example:

Given the following record in your data store:

1
2
3
4
Person 
- Id = 1 
- Name = "John" 
- Email = "john.doe@appian.com" 

If you pass the following data to the data store…

1
2
3
4
Person 
- Id = 1 
- Name = "John Doe" 
- Email = "" 

The result is that your record is changed to list a blank Email field and an updated Name field.

To save form field values, you must create a new node input.

• The data type of the node input must match the data type of your data store entity.
• The first node input you create is saved automatically to the entity.
• Additional node inputs can be created to store process data, but cannot save to the data store. Only the first node input mapped to a data store entity is saved.

Node Outputs

You can create a new Process Variable to store the result or select an existing Process Variable from the available list.

a!writeToDataStoreEntity()

The Write to Data Store Entity smart service is available as an expression function that can be executed inside a saveInto on a component or as part of a Web API.

Syntax

a!writeToDataStoreEntity(dataStoreEntity, valueToStore, onSuccess, onError)

Inputs

• dataStoreEntity (Data Store Entity): The data store entity where you want to save your data.
• valueToStore (Any Type): The data value to create or update.
• onSuccess (Any Type): A list of saves or an HTTP response to execute after the smart service executes successfully. Created with a!save() or a!httpResponse(). The following function variable is available when configuring this input:
  • fv!storedValues (Any Type): The data that was stored or updated in the database.
• onError (Any Type): A list of saves or an HTTP response to execute when the smart service does not execute successfully. Created with a!save() or a!httpResponse().

Best Practices

Review Schema Design Best Practices

Since this smart service works directly with your data store and custom data types, be sure to note the Database Schema Best Practices before implementing.