Writing and Deleting Records Recipes

On This Page

How to Write or Delete a Base Record and Related Records in a Single Node in Appian

This video teaches you to use the Write Records and Delete Records smart service to easily manage record data at any point in the data lifecycle.

Using the Write Records and Delete Records smart services

Appian provides purpose-built smart services, like Write Records and Delete Records, to manage your data operations. These smart services leverage your record type configurations and relationships to handle data changes and their downstream effects automatically.

The recipes on this page demonstrate how to create, update, and delete data using the Write Records and Delete Records smart services. You can use these examples as a reference or adapt them for your own data.

Note: While these recipes use process models, you can achieve the same results in interfaces or expressions using the a!writeRecords() and a!deleteRecords() functions.

Adapt recipes for your data

The recipes below use example record types and data. Record type references are specific to each environment. If you follow along with recipes, or copy and paste these examples into an expression, they will not evaluate.

Use these recipes as a reference, or replace the record type references to use the record type reference in your environment. When replacing record type references, you must use a record type that uses a database as the source.

Create data

The recipes in this section use the Write Records smart service to create new data in one or more record types.

Create a record

Goal: Use the Write Records smart service to make a new record.

No matter what kind of business your app is designed for, creating a new record in a record type is one of the most common data actions. To create a new record, you can build a form that allows users to input information, then pass that information into a process model containing the Write Records smart service.

Tip: The example below illustrates how to manually configure a "Create" action to explain the general workflow of creating a record. In your own application, you can generate a Create record action for faster configuration.

Example

Let's say you need to create a record action that allows users to add new customers in a retail application. The application contains a Customer record type, which stores all customer information. This record type also has record events configured, so you also want to capture an event whenever a new customer is created.

To create this action, you could:

Create a new form interface that allows users to enter the customer's information.
Create a rule input called customer and set the type to the Customer record type. This will allow you to pass customer data to the process model.
Create a new process model and configure the process model properties to use the new form and pass record data:
- Go to File > Properties.
- Go to the Process Start Form tab and select your interface.
- In the Create Process Parameters dialog, click YES. This will automatically create process variables that map to your rule inputs.
Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close
Drag and drop a Write Records node into your process model.
Go to the Setup tab.
For Records Input, select the customer process variable. By default, Record Type for Events populates with the Customer record type. Since the Customer record type has record events configured, the Write Events section can be set up.
For Choose when to write events for the Customer record type, leave the default Always. The smart service will always write an event whenever a new customer is created.
Select the values to write for the event:
- For Event Type, select Created Customer.
- For User, keep the default Process Initiator.
- For Automation Type, select None (User).
- For Timestamp, keep the default Now.
Click OK.
(Optional) Configure a cancel flow.
Save and publish the process model.
Create a record action that launches the new process model.

The process model looks something like this:

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

The node output will return the primary keys of the record and any related records included in the node input.

Goal: Use the Write Records smart service to make a new record and related records.

You can write records and related records in one node if they share a common data source and the relationship has Allow writes and deletes enabled.

The process to create the record and its related records is similar to creating a single record:

You create a form that allows users to update data from different record types.
You pass that information to a process model. The Write Records smart service automatically writes the data to the selected record type and any of its related record types.

Example

A support application needs to create a Case (base record type), along with any associated Tasks and Comments (related record types). The Case record type also has record events configured, so you want to capture an event whenever a new case is created.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

To create this process:

Create an interface where users enter the case details and any initial tasks or comments.
- Add a rule input (ri!case) and set the type to the Case record type.
- Use the relationships to the Task and Comment record type (like, ri!case[recordType!Case.relationships.tasks]) to save related data into the same rule input.
Create a process model and configure the process model properties to use the new form and pass record data:
- Create a process variable (pv!case) using the Case record type. Select the Parameter checkbox.
Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close
- On the Process Start Form tab, select your interface.
- Map the case process variable to the case rule input from the interface.
Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close
Add a Write Records node and set the Records Input to pv!case. The node will write the new Case record, as well as new Task and Comment data included in the case.
In the Write Records node, keep the Record Type for Events as the Case record type and configure which events to capture:
- For Event Type, select Created Case.
- For User, keep the default Process Initiator.
- For Automation Type, select None (User).
- For Timestamp, keep the default Now.
Save and publish the process model.
Create a record action that launches the new process model.

When the process executes, Appian writes the information to the Case record type and its related Task and Comment record types.

Goal: Use the Write Records smart service to make a new record and upload related documents.

Example

For example, let's say you need to create a new record action so users can create a support case and upload documents related to that case, like system logs, images, or contracts.

To manage documents associated with each support case, the Case record type has a one-to-many relationship to a Case Document record type, which is a document management record type. This means that the new case data needs to be written to the Case record type, and the document identifiers for the uploaded documents need to be written to the Case Document record type.

To create this record action, you could:

Create a new form interface that allows users to enter case information and upload related documents. For this example, we'll use the form from the Upload Multiple Documents in an Editable Grid recipe.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Create the following process variables:

Rule Input Name	Type	Description
`case`	Case record type	Stores the user input provided in the Title and Description fields, and the Document and Document Type columns in the grid. Since Case has a one-to-many relationship with Case Document, we can use this process variable to store data for both record types.
`deletedCaseDocuments`	Case Document record type	Stores the documents that are removed from the editable grid when a user clicks X on a row.
`cancel`	Boolean	Stores true or false to indicate if the action was canceled.

Create a process model.
Configure the start form using the interface created in step 1. Automatically create the process variables based on the rule inputs from the interface.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close
Add a Delete Records node to delete the document identifier from any documents removed from the editable grid in the start form. The identifiers of deleted documents are stored in the deletedCaseDocuments rule input, so we'll set the Records input to the deletedCaseDocuments process variable.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close
Add a Write Records node to write the case information to the Case record type and the document identifier to the Case Document record type. Since Case and Case Document are related, we only need to specify the case process variable to write to both record types.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Note: In this example, the Case record type does not have record events configured, so no events will be written.
Add a cancel flow.
Save and publish the process model.
Create a record action that launches the new process model.

Duplicate a record

Goal: Use the Write Records smart service to make a copy of a record.

There are some cases when users may want to duplicate an existing record so they can reuse existing information in a new record. A related action that copies an existing record can save your users a lot of time and effort when working on similar data.

When your process model executes a Write Records node, the node checks for the primary key field on the input record and any related records. When a primary key is included, the smart service updates the record matching that identifier with any changed data passed to the input.

By contrast, if the input record (or related record) does not include a primary key, Appian creates a new record with the data passed to the input. This new record is a duplicate of the original.

We can use this behavior to create a copy of a record with a couple new design objects:

An new Copy interface similar to one you'd use to update an existing case.
A process model with a Write Records smart service node. This process will use the Copy interface as its process start form.

Example

Let's say you're working on a case management application. It has a Case record type for managing support case data. The support representatives using your application want to be able to clone support cases and save time by reusing information already available in another case.

To duplicate a record using this example:

Create a new form interface where users can view and edit an existing support case.
Create a rule input called case and set the value to the Case record type. This will allow you to pass support case data to the process model.

For the form's submit button, set the following properties on a!buttonWidget() to save a null value for the primary key field:

a!buttonWidget(
   label: "Copy",
   submit: true,
   value: null,
   saveInto: ri!case[recordType!Case.fields.id]
)

Note: Depending on the record type, there are likely other record fields that you may want to set as null or to a default value when cloning. This includes fields like create or start dates and task assignees.

Create a process model and use the new interface as the process start form.
Add a Write Records node to take the data from the form (as pv!case) and write a new Case record.
Save and publish the process model.
Create a related action that launches the new process model.

Update data

Goal: Use the Write Records smart service to update an existing record

No matter what type of work your business users are engaged in, at some point they will need to update existing data. These changes are often made with an interface to let users view and edit existing data.

With the Write Records smart service, you can use that interface as the start form of an easy-to-understand process model that writes record data changes. In fact, the smart service is so flexible that, when you generate record actions to create and update data, Appian creates one process model and one interface for both actions.

Example

Let's look at how this generated process changes data in a customer management app.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

The process starts with one data variable called case.
The Write Records node takes data passed from the process start form and creates or updates the record data based on one factor: whether the case includes a value for the record type's primary key field.
- If there is no primary key value included, a new record is created.
- If a value is present, the record identified by that value is updated. For updates, Appian will only write data to the fields you change, so you do not need to include any unmodified fields in the case value.
The process ends after the Write Records node is finished writing data.

Delete data

To a business user, deleted data is that which is no longer accessible. As a developer, you have two options for achieving this result:

Hard deleting permanently removes the data from the record type and source. This might be required if your application deals with sensitive data. When a record type has one-to-many or one-to-one relationships, you can choose to hard delete the related records as well. Alternatively, you can have Appian set the common field value to null to indicate that the relationship was severed.
Soft deleting makes data unavailable using a field like isDeleted or deletedTime. Then, you can use a sync filter on the record type to keep these rows from being synced and available in the record type. If your organization has data retention requirements for auditing purposes or you need to maintain referential integrity, soft deleting lets you meet your retention needs while removing the data from your app.

Note: Sync filters are only available on synced record types. If you're using an unsynced record type, you can use record level-security to hide rows of data that have a field like isDeleted set to true.

Let's look at how to achieve both of these goals.

Hard delete a record

Goal: Use the Delete Records smart service to permanently delete a record.

Sometimes data is created by mistake or your business could be required to delete information on customer request. Users will need the ability to remove record data from your application in those types of situations.

Tip: For faster configuration, you can automatically generate a Delete record action. The generated process model for these actions will use the Delete Records smart service to delete the selected record.

Example

Imagine you need to remove an Employee from the Appian Retail application. You can let users delete record data using a related action connected to a process model. Set a process variable using the record type as the data type to pass the user's selection to the Delete Records smart service.

Create a new form interface that allows users to review the employee's information and confirm they want to delete the Employee record.
Create a rule input called employee and set the type to the Employee record type. This will allow you to pass employee data to the process model.
Create a new process model and configure the process model properties to use the new form and pass record data:
- Go to File > Properties.
- Go to the Variables tab and create a new process variable called employee.
- Set the Type to the Employee record type.
- Select the Parameter checkbox.
Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close
- Go to the Process Start Form tab and select your interface.
- Map your employee process variable to the employee rule input from the interface.
Drag and drop a Delete Records node into your process model.
Go to the Data tab.
For the Records input, set the employee process variable as the Value.
Click OK.
(Optional) Configure a cancel flow.
Save and publish the process model.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close
Create a record action that launches the new process model.

The process node examines the primary key field (in this case, the id field) and deletes that record from the source.

Process details for a Write Records node

Goal: Use the Delete Records smart service to permanently delete a record and its related records.

Sometimes data is created by mistake or your business could be required to delete information on customer request. When the data in question is modeled with a record type and related record types, users will need the ability to remove record data from your application in a seamless way.

Tip: For faster configuration, you can automatically generate a Delete record action. The generated process model for this action will use the Delete Records smart service to delete the selected record and its related records.

Example

Imagine you need to delete an Order from the Appian Retail application. The Order record type has six relationships that you need to consider when building the action to delete these records.

images/delete-records-order-relationships.png

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

When you delete a record, you want to consider whether or not any related data should also be deleted.

In this example:

Order Event History and Order Line Item each store supporting data about orders. This means that if an order is deleted, the related order line items and events are no longer needed.
Case stores data about support cases submitted by customers. You'll want to keep all logged cases even if an order is deleted since support engineers' performance is evaluated based on the number of cases they close.
Address, Customer, and Employee are not reliant on order information since many orders can belong to the same address, customer, or employee.

Based on how the data is related, you'll want to update the relationship configurations for your record types so certain related data is deleted whenever an order is deleted:

Record Type	Relationship Configuration
Order Event History	Select Write or Delete when modifying Orders.
Order Line Item	Select Write or Delete when modifying Orders.
Case	Select Do not write or delete.

You cannot write or delete data from a many-to-one relationship, so you don't need to update the relationships to the Address, Customer, or Employee record types.

Once the relationships are properly configured, you can create a related action to delete a record and any relevant related records.

To create a related action that deletes a record and its related records:

Create a new form interface that allows users to review the order information and confirm they want to delete the Order record. Because line items and the event history will also be deleted, the interface should indicate this fact. To do so, you could use one of these options:
- Show the order line items in a grid component and the order event history in an event history list component on the form.
- Warn the user that this related data will be deleted by stating that fact in the confirmation dialog.
Create a rule input called order and set the type to the Order record type. This will allow you to pass order data to the process model.
Create a new process model and configure the process model properties to use the new form and pass record data:
- Go to File > Properties.
- Go to the Variables tab and create a new process variable called order.
- Set the Type to the Order record type.
- Select the Parameter checkbox.
Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close
- Go to the Process Start Form tab and select your interface.
- Map your order process variable to the order rule input from the interface.
Drag and drop a Delete Records node into your process model.
Go to the Data tab.
For the Records input, set the order process variable as the Value.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close
Click OK.
(Optional) Configure a cancel flow.
Save and publish the process model.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close
Create a record action that launches the new process model.

The process node examines the primary key field (in this case, the id field) and deletes that Order record from the source, as well as any Line Item or Event History records associated with that Order. Any Case records with an orderId value matching the Order's id will now show null for orderId.

Soft delete a record

Goal: Use the Write Records smart service to remove a record from a record type but keep the data available in the source.

Some delete actions need to make the data generally inaccessible in your app, but administrators or other privileged users can retain access in the record type's source (like a database). This type of deleting lets you restore the data if needed.

A related action is a simple way to let users select a record to remove and confirm they want to delete it by clicking a button. This action starts a process model that sets an isDeleted field to true. You can then create a sync filter so only records that have an isDeleted field set to false or null are synced in Appian.

Example

Let's say you need a record action that allows users to delete orders from a retail application. You want the Order data to persist in the data source, but it should not be available in Appian.

The application contains an Order record type, which stores all order information. This record type has record events configured with the following event types:

Created Order
Updated Order
Shipped Order
Delivered Order
Deleted Order

To ensure this action can be traced back to a specific user, we'll want to capture a Deleted Order event.

Here's one way you could create this action:

Create an interface that lets users confirm that they want to delete the order.

For the form's submit button, update the value and saveInto properties so the isDeleted field is set to true:

a!buttonWidget(
   label: "Delete",
   icon: "trash",
   submit: true,
   style: "GHOST",
   color: "NEGATIVE",
   value: true,
   saveInto: ri!order[recordType!Order.fields.isDeleted]
)

Create a new process model and configure the process model properties:
- Go to File > Properties.
- Go to the Variables tab and create a new process variable called order.
- Set the Type to the Order record type.
- Go to the Process Start Form tab and select your interface.
- Map your order process variable to the input from the interface.
Drag and drop a Write Records node into your process model.
Go to the Setup tab.
Add a Write Records node to take the data from the form (as pv!order) and write the soft delete to the Order record type.
For Records Input, select the order process variable. By default, Record Type for Events populates with the Order record type. Since the Order record type has record events configured, the Write Events section can be set up.
For Choose when to write events for the Order record type, leave the default Always. The smart service will always write an event whenever an order is soft deleted.
Select the values to write for the event:
- For Event Type, select Soft Deleted Order.
- For User, keep the default Process Initiator.
- For Automation Type, select None (User).
- For Timestamp, keep the default Now.
Save and publish the process model.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close
Create a related action that launches the new process model. Use the Order record type in the related action context as rv!record.

In the Order record type, add a sync filter so only records with an isDeleted value of null or false are synced. This filter must be created using expression mode because you need to use the OR operator for the two filter conditions.

a!queryLogicalExpression(
  operator: "OR",
  filters: {
    a!queryFilter(
      field: "IS_DELETED", /* The filter matches the source field's name, not the record field */
      operator: "is null"
    ),
    a!queryFilter(
      field: "IS_DELETED",
      operator: "=",
      value: false()
    )
  },
  ignoreFiltersWithEmptyValues: true
)

Goal: Use the Delete Records smart service to remove a related record but keep the data available in the source.

Some related records, like line items on an order, are managed in the context of a base record. In those situations, your interface may need to allow users to select and delete these related records.

Appian has many interface components for selecting data, including checkboxes and radio buttons. In this example, we'll use a dynamic link to create clickable text that saves a value to a rule input property.

Example

Let's say you need a record action that allows users to update a support case, including any of the comments on the case. Comments are in a separate record type and referenced in the Case through a record type relationship.

In this scenario, we'll mark the comment as deleted and use a sync filter to exclude deleted comments from the record type. Since we are soft deleting the comments, they are still available in the source for auditing purposes.

A user should be able to delete comments if they meet either of the following conditions:

They are the comment's author.
They are a manager of the support department.

In the following example, if Alice K. views the case, she will only be able to delete her comment.

images/soft-delete-comment-interface.png

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Since a case can have one or more comments, a reusable interface will let you add multiple instances of these components without unnecessarily repeating code. You can see an example of how to do this in our video explaining the use of a!forEach() in interfaces.

Before you build the record action:

Create the interface that will display each comment.
Name the interface commentBox.

To create this action, you could:

Create an interface that lets users view the case and select the comments the want to delete.
In the interface, create a rule input called case and set the type to the Case record type.
In the interface, add a section layout where you want the case comments to appear.

In the section's contents parameter, add a a!forEach() loop that uses the commentBox interface to display each comment on the case. Each comment box is followed by a dynamic link that sets the isDeleted field to true when clicked.

a!forEach(
 /* 
 The items evaluated for each loop are the Comments related to each case.
 To loop through them, you must specify the record type relationship here.
 */
 ri!case[recordType!Case.relationships.Comment],
  {
    if(
      fv!isFirst,
      a!horizontalLine(color: "#ffffff"),
      a!horizontalLine(
        showWhen: and(
        fv!item[recordType!Comment.fields.isDeleted] <> true,
        count(fv!item) > 1
      ))
    ),
    if(
      fv!item[recordType!Comment.fields.isDeleted],
      a!richTextDisplayField(),
      rule!commentBox(fv!item),
    ),
    a!linkField(
      labelPosition: "COLLAPSED",
      links: {
        a!dynamicLink(
          label: "Delete comment",
          value: true(),
          saveInto: ri!case[recordType!Case.relationships.Comment][fv!index][recordType!Comment.fields.isDeleted],
          showWhen: {
            and(
              fv!item[recordType!Comment.fields.isDeleted] <> true,
              if(
                or(
                  loggedInUser() = fv!item[recordType!Comment.fields.createdBy],
                  a!isUserMemberOfGroup(loggedInUser(), "AT Support Managers")
                ),
                true(),
                false()
              )
            )
          }
        )
      }
    )
   }
)

Create a new process model and configure the process model properties:
- Go to File > Properties.
- Go to the Variables tab and create a new process variable called case.
- Set the Type to the Case record type.
- Go to the Process Start Form tab and select your interface.
- Map your case process variable to the case rule input from the interface.
Drag and drop a Write Records node into your process model.
Go to the Setup tab.
Add a Write Records node to take the data from the form (as pv!case) and write any soft deletes to the Comment record type.
For Records Input, select the case process variable. By default, Record Type for Events populates with the Case record type. Since the Case record type has record events configured, the Write Events section can be set up.
For Choose when to write events for the Case record type, leave the default Always. The smart service will always write an event whenever an case is changed.
Select the values to write for the event:
- For Event Type, select Updated Case.
- For User, keep the default Process Initiator.
- For Automation Type, select None (User).
- For Timestamp, keep the default Now.
Save and publish the process model.
In the Case record type, create a related action that launches the new process model. Use the Case record type in the related action context as rv!record.

In the Comments record type, add a sync filter so only records with an isDeleted value of null or false are synced. This filter must be created using expression mode because you need to use the OR operator for the two filter conditions.

a!queryLogicalExpression(
  operator: "OR",
  filters: {
    a!queryFilter(
      field: "IS_DELETED", /* The filter matches the source field's name, not the record field */
      operator: "is null"
    ),
    a!queryFilter(
      field: "IS_DELETED",
      operator: "=",
      value: false()
    )
  },
  ignoreFiltersWithEmptyValues: true
)

Feedback

Was this page helpful?

Writing and Deleting Records Recipes

Using the Write Records and Delete Records smart services

Adapt recipes for your data

Create data

Create a record

Create records and related records

Create a record and related documents

Duplicate a record

Update data

Delete data

Hard delete a record

Hard delete a record and its related records

Soft delete a record

Soft delete a related record

Feedback