The Write to Multiple Data Store Entities Smart Service writes multiple CDT values to multiple entities within the same data store based on your input. This differs from the Write to Data Store Entity Smart Service because you can update multiple entities within a single database transaction.
The entities to be updated and the values to update each entity with are defined by the Value to Store node input of type EntityData. The transaction produces a Node Output of type EntityData containing the actual stored values of each EntityData object passed to the smart service which can be filtered to retrieve the stored values.
If any write to the data store fails, no data is written to the data store.
Note: 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. Learn more about CDT Relationships.
You have an application that manages a sales cycle with a process which needs to update three different entities based on an Account Executive's work on the sale.
When the Account Executive has a call with a potential customer, he/she updates the status of the different opportunities discussed and the customer account.
Using this smart service, you can have all three data store entities updated within the same transaction. This way, if an error occurs while writing to one of them, the others entities will not update either - leaving the data in a consistent state as if they were never modified.
The user running the smart service must have Viewer rights to the data store that contains the entities defined in the EntityData node input. Attempting to complete this task without the proper user rights generates an error message for the process administrator and pauses the process.
Category: Data Services
Icon:
Assignment Options: Always Unattended
This section contains tab configuration details specific to this smart service. For more information about common configurations see the Process Node Properties page.
Name | Data Type | Description | Required | Multiple |
---|---|---|---|---|
Value to Store | EntityData | The target entity and data values to store in the target entity. |
No | Yes |
Only the Value to Store input value is used when writing data to the data store. All other inputs are ignored.
You can write to multiple EntityData inputs through one transaction by creating an array of EntityData objects for the EntityData value.
See also: EntityData Data Type
If you set the Value to Store input to modify data in three data store entities, using process variables for the entities and process variables populated in a prior process step for the data values, your input value may resemble this:
1
2
3
4
5
6
7
8
={
a!entityData(entity: pv!ENTITY_OPPORTUNITIES,
data: {pv!RadiationOpp,pv!NewBusinessOpp}),
a!entityData(entity: pv!ENTITY_ACCOUNT,
data: {pv!AcmeAccount}),
a!entityData(entity:pv!ENTITY_AE_NOTES,
data:{pv!ListOfNotesFromAccountExec})
}
If you use the is appended to output operator on nodes in a prior process step to collect EntityData process variables and create an array of EntityData values, your input value may resemble this:
1
=pv!ArrayOfEntityDataToStore
If the EntityData input contains a null or empty data field value, the EntityData object still returns as part of the EntityData output array with the null or empty data field.
Name | System Data Type | Description |
---|---|---|
Stored Values | EntityData | An array of type EntityData listing each EntityData object passed to the data store after evaluation and in the order evaluated. |
For Example 1 in the above Example inputs, you can use the known indices of the EntityData array values to store data from the outputs into process variables of the correct data type using the following expressions:
1
2
3
StoredValues[1].data → pv!StoredOpportunities
StoredValues[2].data → pv!AcmeAccount
StoredValues[3].data → pv!NewNotes
For Example 2 in the Example inputs, since the EntityData input value entered is an array of varying length based on runtime conditions, you can use the reduce() function to accumulate the data sent to the entity.
To do so, first create a rule similar to the following:
1
2
getDataFromEntityDataForEntity(ri!data, ri!EntityData, ri!Entity)
=append(ri!data, if(ri!EntityData.entity=ri!Entity, ri!EntityData.data, {})
Then use this rule with the reduce() function to define a node output similar to the following that saves into a multiple process variable of type Ticket:
1
reduce(rule!getDataFromEntityDataForEntity, {}, ac!StoredValues, cons!ENTITY_TICKET)
This node output will return a list of data where entity=ticket
into your process variable of type Ticket.
If you use this smart service to add or update data in a database table, and that table is the source of a record type with data sync enabled, those changes will be automatically synced in Appian.
Depending on how your table data is structured in the CDT, the maximum number of rows that can be automatically synced will vary:
If you update more than the maximum number of rows, the smart service will successfully write to the data source, but the sync will fail.
If the smart service fails because there is an issue connecting to the database, like if VPN connection fails so you can't write your changes, Appian will automatically retry the smart service and the sync operation up to three times (with two seconds between each retry). After three attempts, the sync will fail and the record data will be unavailable.
See Troubleshooting Data Sync for more information on the different sync errors.
The Write to Multiple Data Store Entities smart service inserts or updates data one row at a time. Bulk inserts and updates are not supported. If your network latency is near the upper bound of the recommended round-trip time for TCP communication with your data source, you should use the Execute Stored Procedure smart service or Query Database smart service instead to perform bulk inserts and updates.
The Write to Multiple Data Store Entities smart service is available as an expression function that can be executed inside a saveInto on a Interface Component or as part of a Web API.
a!writeToMultipleDataStoreEntities( valuesToStore, onSuccess, onError )
Keyword | Type | Description |
---|---|---|
|
List of EntityData |
A list of the target entity and data values to store in the target entity, created with a!entityData(). |
|
Any Type |
A list of saves or an HTTP response to execute when the smart service executed successfully. Created with |
|
Any Type |
A list of saves or an HTTP response to execute when the smart service does not execute successfully. Created with |
All data is written to the data store in the order in which it was given.
Error Message | Cause |
---|---|
The list of EntityData passed to the smart service contains entities from different data stores. All entities must belong to the same data store. No values have been written. |
Not all entities belong to the same data store. |
The EntityData at index [{0}] has an entity field that does not have a value. Each EntityData passed to the smart service must have a valid value for the entity. No values have been written. |
A Data Store Entity value of a EntityData value is null. |
An error occurred while trying to retrieve the data store entity [id={0}]. Verify that the data store and entity have not been deleted. Details: {1} |
The referenced entity or associated data store has been deleted or is invalid. |
The data source [{1}] could not be reached while trying to write to the data store: {0}. |
An error occurred when connecting to the data source for the associated data store. |
An error occurred while trying to write to the data store: {0}. No values have been written. Details: {1} |
A database constraint or similar error occurred while attempting to save data to the database. |
The user [{0}] does not have sufficient privileges to write data to the data store [{1}]. No values have been written. Verify that the data store has the correct security settings. Details: {2} |
The user executing the node does have at least Viewer rights for the associated data store. |
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.
As this smart service updates multiple entities in a single database transaction, some overhead is introduced in the write process to ensure atomicity. When transactional aspects of this smart service are not required, it is preferable to use multiple instances of the Write to Data Store Entity Smart Service to ensure better performance.
Feature | Compatibility | Note |
---|---|---|
Portals | Partially compatible | Can be used with Appian Portals if it is connected using an integration and web API. |
Offline Mobile | Incompatible | |
Sync-Time Custom Record Fields | Incompatible | |
Real-Time Custom Record Fields | Incompatible | Custom record fields that evaluate in real time must be configured using one or more Custom Field functions. |
Process Reports | Incompatible | Cannot be used to configure a process report. |
Process Events | Incompatible | Cannot be used to configure a process event node, such as a start event or timer event. |
Write to Multiple Data Store Entities Smart Service