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.

Properties

• Category: Data Services

• 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

See also: Record Type

Node outputs

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"
)

Create and update related records

If you have a record type with relationships, you cannot use relationship references in a Write Records node. Any related record fields are ignored by the smart service.

Instead, your process model must include a separate node for each record type and related record type you want to update. See an example below.

Unsupported fields in the records input

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.

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. When creating a web API, select the Write Records template to generate the object with this function automatically configured.

Syntax

a!writeRecords( records, onSuccess, onError )

Parameters

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:

• The record type's row limit is exceeded.
• A record field contains an invalid value.
• The record type's source filter is invalid (for example, if the source field is no longer available).

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=).

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(),
    )
  }
)

Create records and related records

If you have a record type with relationships, you cannot use relationship references in a Write Records node. Instead, your process model must include a separate node for each record type and related record type you want to update.

Imagine you are building an interface that will allow users to enter information about new salespeople joining the company. To represent people, your application's data model includes three record types:

• Person, the base record type with fields like firstName and lastName.
• Employee, a related record type for data like hireDate and dateOfBirth.
• Sales Person, a related record type with fields for salesQuota, commissionRate.

In this example, our interface collects the complete set of information about a new salesperson; however, we'll need three different Write Records smart services to update the different record types since you cannot use relationship references in the smart service.

The process model to create a new Sales Person will look something like this:

This process model uses the interface as a start form so new user data is passed to the process model and set as the initial values for three process variables (person, employee, and salesperson).

The first Write Records node uses the person variable as the Records input to create the new Person record.

Since we'll need to reference the new person ID in order to create the related records in the Employee and Sales Person record types, we'll store the person ID in the output. To do this, we'll go to the Output tab and set the Records Updated result to pv!person.

Now the process variable includes the id generated for the person (in this example, the value is 20778).

Next, a script task automatically sets the personId of the employee and salesperson variables to 20778 (the id of the Person record).

The process will then write the related Employee and Sales Person records in their own nodes, and they will be correctly associated with the Person.

Feature compatibility

Versions

A smart service consists of a function and a node. There are some instances when the smart service function is evolved separately from the smart service node. When the function or node is evolved, a new version of the function or node is available.

The following sections detail the different versions of the Write Records function and Write Records node.

Node versions

You can identify the version of a smart service node by looking at node type and version.

To review a node's type and version:

1. In the Process Modeler, click Tools > Generate Documentation.
2. In the generated documentation, review the Node Type and Version for the specific node.

If you are using a previous version, be sure to refer to the corresponding documentation from the list below. To use the latest version of the node, replace the old version of the node with a new node.

Feedback