Write Records Smart Service

Overview

The Write Records smart service is a powerful tool that allows you to easily insert or update data in the source system and then automatically sync the changes in Appian. The service lets you add or update one or more records at a time per node.

To use this smart service, the record type you want to update must meet the following conditions:

  • The record type uses a database as its source.
  • The record type has data sync enabled.

Records can only be updated for one record type at a time. To update a record and its related records, you must first update the base record and then update your related record with another Write Records node.

Permissions needed

The user executing this activity must have Viewer permissions to the selected record type in order to update or insert information. If the user does not, the node will fail and pause the process with an exception.

Since the Write Records Smart Service works directly with your record type's source, read the recommendations in Data Modeling with Appian Records before implementing this smart service.

Properties

  • Category: Data Services
  • Icon: Create Folder icon
  • Assignment Options: Automated activity

Configuration options

This section contains 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
Records List of Any Type A list of records in one record type and the data to be updated for each. Up to 50,000 records can be updated per node. Any related record data is ignored. Yes Yes
Pause On Error Boolean Determines whether the node should pause by exception if an error occurs writing to the source. Default: true. No No

See also: Record Type

Node outputs

Name Data Type Description
Records Updated List of Any Type A list of records updated by the smart service
Error Occurred Boolean Returns true if any write to the source system or Appian fails; returns false if all writes succeed
Errors List of Any Type The error that occurred when writing the records and the list of records that failed to write. This is only returned when the Pause On Error input is false.

Usage considerations

Update existing data

When passing data to the Write Records smart service from an interface, use the record type constructor syntax. To update existing data, the record must include a primary key value.

A new record will be created when one of the following is true:

  • The data source table is set to AUTO_INCREMENT the primary key column.
  • The record type's primary key field is configured to use a sequence to generate key values.
  • The source table is not configured to AUTO_INCREMENT or use a sequence, and your app provides the primary key value.

For example, if you want to update an employee record, you must pass the employee's Id to the Write Records smart service.

When you update an existing record, only include the data you want to change. Imagine your Employee record type has fields for firstName and lastName, but you only need to update an employee's last name from Anderson to Kwan. You can pass just the record's identifier and the new lastName. Any fields not included in the update are ignored. In this example, the firstName field is not included, so the employee's first name remains unchanged.

1
2
3
4
recordType!Employee(
  recordType!Employee.fields.id: 233,
  recordType!Employee.fields.lastName: "Kwan"
)

Update custom record fields

Because the smart service updates the database source of your record type, you cannot include custom record fields in the records input. These fields are defined by and exist only in Appian, so attempting to write values for them will have no effect.

The Write Records smart service does not support writing to related record types through the base record type. Any related record fields are ignored by the smart service.

a!writeRecords()

The Write Records 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!writeRecords( records, onSuccess, onError )

Parameters

Keyword Type Description

records

Any Type

This parameter uses a list of map of all the records to update (up to a maximum of 50,000 records). Use the recordType! domain to reference your record type. If any related data is included in this parameter, that related data is ignored.

onSuccess

Any Type

A list of saves or an HTTP response to execute when the smart service writes data successfully. Created with a!save() or a!httpResponse(). Use fv!recordsUpdated to reference the updated records in the success response. For more information, see Function Variables.

onError

Any Type

A list of saves or an HTTP response to execute when the smart service does not write data successfully. Created with a!save() or a!httpResponse(). Use fv!errors to reference any errors from the source.

Automatic refresh on record views

When you use this smart service on a record view, the view will automatically refresh with the latest record data.

This means that when your record view interface has a Record Action component that triggers the Write Records smart service, or a button component that triggers the a!writeRecords() function, the record view data will automatically refresh after the write occurs.

This refresh behavior only applies to data supplied by rv!record. If your record view definition uses rv!identifier or a local variable to supply the record data, the data will not automatically refresh; instead, you will need to configure additional refresh behavior.

Possible errors

This section explains some of the common reasons the Write Records smart service might fail.

Configuration errors

Configuration errors can occur when node inputs are misconfigured and attempts to write to the source will not succeed. Some examples of misconfiguration include:

  • Using an unsupported record type (such as a record type with a non-database source).
  • An error in the expression calling the process model or the a!writeRecords() function.

Errors with the data source

Appian is unable to change data in the source in some circumstances. These situations include:

  • Schema mismatches such as conflicting data types.
  • Database connection problems like timeouts or invalid credentials.

If Appian is unable to write to the database, the record data will still remain available even if the smart service fails.

Errors syncing data changes

When Appian attempts to sync changes to the source data, the sync will fail when one of the following occurs:

If Appian is unable to sync changes from the source, the record data will be unavailable. For more information on the different types of sync errors and steps to resolve these errors, see Troubleshooting Syncs.

Examples

The following examples show the different ways you can use the Write Records smart service to create or update your record data.

The following example data is from the Appian Retail application, available for free in Appian Community Edition. To try the example code yourself, sign in to Appian Community to request the latest Appian Community Edition site.

Create a new record using a process model

Imagine you need to add a new person in the Appian Retail app. You can let users submit record data using a interface connected to a process model. Set a process variable using the record type as the data type to pass user data to the Write Records node.

The process node returns any record fields not passed to the process after it writes the data to the source. In the following example, the Write Customer records node returns the primary key and its value (id=101), as well as an optional record field (emailPromotion=).

Process details for a Write Records node

Appian can automatically generate a Create or Update record action. The generated design objects use the Write Records smart service in the workflow powering the new action.

Create a new record using an expression

To add a new Person record using the a!writeRecords() function, you'll use a record type constructor in the records parameter with the new field values you want to include. In this case, you create a new Person record by providing data for the firstName, lastName, and modifiedDate record fields.

1
2
3
4
5
6
7
8
9
a!writeRecords(
  records: {
    recordType!Person(
      recordType!Person.fields.firstName: "Karen",
      recordType!Person.fields.lastName: "Anderson",
      recordType!Person.fields.modifiedDate: now(),
    )
  }
)

If you have a record type with relationships, you cannot use related records in the a!writeRecords() function. Instead, you must include separate record type constructors for the related records using the Person id as a foreign key.

In this example, we'll create three new records—one in three different record types—that together contain all of the data required to represent a sales person at the Appian Retail company. The record types are Person (the base record type), Employee, and Sales Person.

First, in the records parameter, create a Person record type constructor. Set the primary key field (id) to null and provide data for the firstName, lastName, and modifiedDate record fields.

1
2
3
4
5
6
7
8
9
10
a!writeRecords(
  records: {
    recordType!Person(
      recordType!Person.fields.id: null,
      recordType!Person.fields.firstName: "Mary",
      recordType!Person.fields.lastName: "King",
      recordType!Person.fields.modifiedDate: now(),
    )
  }
)

This expression returns an id value of 102 we'll use in two more a!writeRecords() functions to create related records with information about that person.

1
2
3
4
5
6
7
8
9
a!writeRecords(
  records: {
    recordType!Employee(
      recordType!Employee.fields.businessEntityId: 102,
      recordType!Employee.fields.birthDate: date(1981,3,2),
      recordType!Employee.fields.jobTitle: "Sales Representative"
    )
  }
)
1
2
3
4
5
6
7
8
9
10
a!writeRecords(
  records: {
    recordType!salesPerson(
      recordType!salesPerson.fields.id: 102,
      recordType!salesPerson.fields.salesQuota: 300000,
      recordType!salesPerson.fields.bonus: 10000,
      recordType!salesPerson.fields.commissionPercent: 0.0190
    )
  }
)
Open in Github Built: Fri, Sep 23, 2022 (01:18:25 PM)

On This Page

FEEDBACK