Write to Multiple Data Store Entities Smart Service

Overview

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.

See also: Write to Data Store Entity Smart Service

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.

See also: CDT Relationships

Example Use Case

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.

Permissions Needed

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.

Properties

  • Category: Data Services (Integration Services)

  • Icon:

  • Assignment Options - Always Unattended

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

Name Data Type Description Required Multiple
Value to Store EntityData The target entity and data values to store in the target entity.
  • Entering a null or empty value does not produce an error or write transaction.
  • The value can be populated by a process variable created prior to executing this smart service.
  • Every EntityData value must have a valid value for the Data Store Entity field.
  • 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.

    • All entities defined in the array must be of the same data store.
    • Arrays can be constructed using dictionary syntax as the EntityData level of the node input or populated in the process flow prior to executing this smart service and passed to the node input.

    See also: EntityData Data Type

    Example Inputs

    Example 1

    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
    
    ={
    {entity:pv!ENTITY_OPPORTUNITIES,
     data:{pv!RadiationOpp,pv!NewBusinessOpp}},
    {entity:pv!ENTITY_ACCOUNT,
     data:{pv!AcmeAccount}},
    {entity:pv!ENTITY_AE_NOTES,
     data:{pv!ListOfNotesFromAccountExec}}
    }
    

    Example 2

    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
    

    Node Outputs

    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.
    Example Output Use

    Example 1

    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
    

    Example 2

    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.

    a!writeToMultipleDataStoreEntities()

    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.

    Syntax

    a!writeToMultipleDataStoreEntities(valuesToStore, onSuccess, onError)

    Inputs

    • valuesToStore (List of EntityData): A list of the target entity and data values to store in the target entity, created with a!entityData().
    • onSuccess (Any Type): A list of saves or an HTTP response to execute when the smart service executed successfully. Created with a!save() or a!httpResponse(). The following function variable is available when configuring this input:
      • fv!storedValues (EntityData): An array of type EntityData listing each EntityData object passed to the data store after evaluation and in the order evaluated.
    • 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().

    Run-Time Behavior

    All data is written to the data store in the order in which it was given.

    • Casting of CDTs will occur if the data type of an EntityData data field does not match the target entity data type.
    • If any failure occurs during the transaction, all changes will be rolled back and the data in the data store will not be modified.
    • If none of the data fields contain values to store or if the EntityData array is an empty list, no transaction occurs and nothing is recorded in the performance log.
    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.

    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 Schema Design 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.

    FEEDBACK