Manage Documents with Record Types

This page explains how to configure record types for documents stored in Appian or in external systems.

When to use record types to manage documents

Use record types to manage documents when the documents are created and maintained as part of your application workflows.

Whether users attach system logs to support cases or upload expense forms, you can use record types to manage documents, regardless of where they are physically stored.

Why use record types to manage documents

Using record types to manage documents provides the following benefits:

• Unified Data Fabric: Create relationships between documents and business data to display all relevant information in one place.
• Granular Security: Configure record-level security to control who can see which documents.
• Simplified Process Automation: Streamline your process models by letting Appian handle folder management automatically. For external files, use the Return External Document smart service to seamlessly integrate them into AI skills, email nodes, or other process activities.
• AI-Powered Insights: Leverage smart search and documents chatbot to allow users to explore and interact with documents.
• Consistent User Experience: View and download documents directly in your interfaces, regardless of whether the files are stored in Appian or an external system.

Required objects

To use a record type to manage documents, you must configure a document management record type. A document management record type determines how documents are secured and referenced in your applications.

You can create a new record type or use an existing record type that already holds document metadata—the key requirement is that it has the appropriate fields and configuration.

The configuration requirements and supporting objects for the document management record type vary based on where documents are stored.

Required objects for documents stored in Appian

To manage documents stored in Appian, you need the following object:

• Document management record type: A record type configured to manage documents. See configure a document management record type for Appian-stored documents. Appian automatically generates and manages all other supporting objects.

Required objects for documents stored in external systems

To manage documents stored in an external system, you need the following objects:

• Connected system: An HTTP connected system, pre-built connected system, or plug-in connected system that authenticates with the external system.
• Integration: An integration that retrieves documents from the external system.
• Document management record type: A record type configured to manage external documents. See configure a document management record type for externally-stored documents.

Data model for managing documents

You can create multiple document management record types in your application to support different business entities.

For example, in a human resources application, you could have the following document management record types:

• SCA Case Document: Manages case documents related to the SCA Case record type.
• SCA Candidate Document: Manages candidate documents related to the SCA Candidate record type.

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

The best way to model your document management record types depends on where your documents are stored.

Data model for Appian-stored documents

When documents are stored in Appian, the document management record type acts as a join table between your business data and the Document record type. The Document record type is a system-provided object that contains information for all files stored in Appian and managed by record types.

For example, the Case Document record type is a document management record type that manages multiple documents to each case in the Case record type. The Case Document record type also relates the Document record type to access the properties for each document.

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

Required fields for Appian-stored documents

To manage Appian-stored documents, the document management record type must have the following fields:

• Primary key field: The unique identifier for the record.
• Document field: A field of type Document that stores the document identifier. When you add this field, Appian automatically creates a many-to-one relationship to the Document record type.
• Foreign key field: (Optional) A field that links the document to a specific business record, such as a case or customer. Use this field to add a many-to-one relationship with your business data record type.

Data model for externally-stored documents

To manage documents stored in an external system, you don't have to use that system as the source of your document management record type. Instead, you'll configure a download integration on the record type to retrieve the actual files.

Because the integration handles the file retrieval, choose the source of your document management record type based on your data needs, not just the physical location of the files.

To determine the best source for your document management record type, evaluate whether you need to add relationships between documents and other data, or if you need to capture additional document metadata.

Use the following table to determine the best source for your record type based on your requirements:

If you need to…	Recommended source
Add relationships or capture metadata that the external system does not provide	Database table
Map existing metadata directly and you do not need to add relationships	External system
Map existing metadata and relate documents to business data	Create two record types

Required fields for externally-stored documents

Regardless of the source you choose, your document management record type must have the following fields:

• Primary key field: The unique identifier for the record.
• External document identifier field: A field that maps to the unique identifier for each document in the external system. The data type for this field must match the identifier used by the external system, such as Text for a URL or Number (Integer) for a numerical code. You will use this field to configure the download integration.

Use a database table as the source

Use a database table as the source when you need to relate external documents to your business data, or when you need to capture metadata that the external system does not provide (like createdBy or isActive).

Using a database table as the source allows you to create common fields, like caseId or customerId, to add relationships to other record types. You can also add fields to capture document metadata that isn't available in the external system.

Requirement: The database table must include a field to store the external document identifier, like the URL or specific numerical identifier. You will use this field to configure the download integration.

Example: A Case Document record type acts as the document management record type and uses a database table as its source. It includes the following fields:

• Id: (Required) The primary key field for the record.
• documentURL: (Required) Stores the unique document identifier in the external system. This field is used to call a specific document from the download integration also configured on the record type.
• recordId: The foreign key used to relate documents to a case in the Case record type.
• createdBy: Captures metadata (when the document was created), which is not available in the external system.

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

Use the external system as the source

Use the external system as the source if it provides all necessary metadata. This allows you to map external data directly to fields in the record type.

However, because you cannot add new fields to a web service source, you cannot create relationships that require a foreign key on the document management record type. You can still create relationships to other data, provided the foreign key exists on the related record type (for example, a Case record that stores a documentId to reference a document).

Example: A Company Document record type acts as the document management record type. This record type connects directly to the external system.

While the external source provides all of the following fields, only the identifiers are required to manage the external documents in Appian:

• id: (Required) The primary key field.
• documentURL: (Required) The external identifier field provided by the source, which is used for the download integration.
• createdBy: The user who created the document.
• createdOn: The date and time when the document was created.
• isActive: Whether or not the document is still in use.

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

Use two record types to manage external documents

If the external system contains all necessary metadata, but you also need to relate documents to business data, use a hybrid approach with two record types:

• A document management record type that connects to the external system.
• A join record type that connects to a database table. This table should include a field for the external document's unique identifier and any common fields needed to create relationships.

Example: Case documents are stored in an external system, which includes all the necessary metadata; however, you want to relate those documents to each case in the Case record type. To manage the external documents in this scenario, you'd create two record types:

• Case Document record type: This is the document management record type. It connects to the external system to retrieve document properties and includes the external document identifier (documentId) used for the document download integration.
• Case-to-Document record type: This is a join record type that connects to a database table. It contains the foreign key field (recordId) to relate documents to the Case record type, and the external document identifier (documentId) to relate to the Case Document record type.

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

Create a document management record type

A document management record type can manage documents stored in Appian or in an external system. A single record type cannot manage documents from both sources.

You can either create a new record type or configure an existing record type that already holds document metadata. The configuration steps for a document management record type differ depending on where your documents are stored.

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

Create a record type for Appian-stored documents

You can quickly generate a document management record type to manage documents stored in Appian using codeless data modeling.

To manually create this record type:

1. Create a record type. The record type can use Optimized Data Access or Direct Data Access.

2. Add a field of type Document.

   

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

3. (Optional) Add additional fields to capture other information relevant to your document. For example, an isActive field to indicate when a document should not be used anymore.

4. (Optional) Add relationships to other record types containing relevant data.

   By default, the record type will have a many-to-one relationship to the Document record type. This record type contains key information about all the documents in your environment that are stored in Appian and managed by record types.

5. Click SAVE.

Generated folder for Appian-stored documents

When you generate or create a document management record type for Appian-stored documents, Appian automatically generates a document folder to store documents for the record type. The generated document folder will be created in the Record Document System Knowledge Center, which is provided out of the box in every environment.

Generated document folders are not accessible when browsing objects in Appian Designer. If you need to reference the generated document folder in a Document Management smart service or plug-in, use the a!documentFolderForRecordType() function.

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

Configure a record type for externally-stored documents

To manage documents stored in external systems, you must manually configure your record type and its supporting integration. You can configure an existing record type that already holds document metadata, or create a new record type. You cannot use the codeless data modeling flow for externally stored documents.

To configure a record type to manage documents stored in external systems:

1. Create a connected system or download a connected system plug-in to authenticate and access the external system.
2. Create an integration to return documents from the external system. Ensure the integration meets the integration requirements.
3. Create a record type, or open an existing record type that holds document metadata. The record type can use Optimized Data Access or Direct Data Access.
4. Ensure the record type contains a field for the unique identifier of documents in the external system. This field must match the data type of the rule input in your integration.

5. Go to the Documents page of the record type.

   

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

6. Click SELECT INTEGRATION. The Select Integration dialog appears.
7. For Integration, select the integration that allows users to view and download documents. The Rule Input and Rule Input Type are automatically populated.

8. For Field to Map to Rule Input, select the field containing the unique identifier of documents in the external system.

   

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

9. (Optional) Test the integration by entering a title in Search Record Titles and clicking DOWNLOAD.
10. Click DONE.
11. Click SAVE.

Integration requirements for external documents

The download integration used by the record type must have the following configuration:

• Rule Inputs: The integration must have exactly one rule input. You will map this input to a record type field when configuring the Document Download integration.

• Response Body Parsing: The integration must have one of the following configurations:

  • Convert binary to Appian document.
  • Convert JSON to Appian Value. (You must also enable Convert base64 values to Appian documents).

When the record type calls this integration, documents are always saved to a temporary document folder for 24 hours, regardless of any save location configuration. For HTTP integrations, set the Save Document(s) In property to Record Type to keep the save behavior consistent when you call the integration from other parts of your application. For non-HTTP integrations, you can configure any save location—documents are still saved to the temporary folder when called by the record type.

Generated folder for externally-stored documents

When you create a document management record type for externally-stored documents, Appian automatically generates a temporary document folder.

Appian automatically stores and removes external files from this folder on a regular basis. Temporary document folders are not accessible when browsing objects in Appian Designer.

Keep external document metadata in sync

To keep your document management record type up to date when document metadata changes in the external system, use the same sync options available to any synced record type. For example, you can schedule syncs to periodically capture changes from the external system, or use web APIs to trigger a sync when data changes.

For more information, see Configure Sync Options.

Move documents from a folder to a record type

If your existing application stores documents in folders and uses a record type with a Number (Integer) field for document identifiers, you can convert that record type to a document management record type. This enables smart search and lets you fully access and secure new and existing documents with just a few modifications.

To move existing documents to a document management record type:

1. In your existing record type, change the data type of the field that stores document identifiers to type Document.

   When you save the change to the record type, it will automatically generate a document folder for the record type and add a relationship to the Document record type.
   

2. Create a process model to move documents to the generated document folder for the record type. For example:

   

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

3. Update any objects that create or update documents so those documents are stored in the document folder for your record type. Use the a!documentFolderForRecordType() function to access the appropriate folder.
4. In your existing process models, continue to write the document identifier to your record type. You can remove folder management tasks since document organization and security is controlled by the record type.

Document security

Document security is controlled by the document management record type. The document management record type provides a unified security model whether the files are stored in Appian or an external system.

The following security applies to documents managed by a document management record type:

• Record type security: Users must have at least Viewer permission to the record type to view and manage the documents.
• Record-level security: (Optional) You can configure record-level security to ensure users only see documents relevant to them, such as files associated with a specific case, department, or region.
• Field-level security: (Optional) You can configure field-level security to hide sensitive metadata fields, like internalComments or securityClassification, from users who should not see that specific information.

When you create documents in Appian, they will only be available to the document creator and system administrators. Once you write the document identifier to the document management record type, all record type security settings automatically take effect.

Use documents in your applications

After you create a document management record type, you can use it to reference and interact with documents throughout your applications:

• Display documents: Configure the Document Viewer component or Document Image component in your interfaces.

  For examples, see:

  • Display Appian-stored documents in a Document Viewer or Document Image component.
  • Display externally-stored documents in a Document Viewer or Document Image component.

• Download documents: Configure the Document Link component in your interfaces.

  For examples, see:

  • Download Appian-stored documents from a record type
  • Download externally-stored documents from a record type

• Search across document content: Enable smart search on your document management record type to perform semantic or lexical searches on documents stored in Appian or an external system.

  For examples, see:

  • Search across Appian-stored documents
  • Search across externally-stored documents

• Use documents in process models: Pass documents throughout your workflows, like to an AI skill or Send Email node. Depending on where documents are stored, you'll either pass the Document field directly from a process variable or use the Return External Document smart service to retrieve the file from your external system.

  For an example, see:

  • Document Classification Tutorial

• Manage document metadata: Use the Write Records and Delete Records smart services to update document properties, like whether the document is reviewed or deprecated.

Create and delete documents

This section applies only to documents stored in Appian. You cannot use record types to create or delete documents in external systems.

When you create a document management record type to manage documents stored in Appian, you can configure different interface components, smart services, and plug-ins to create and delete documents managed by that record type.

As you configure these elements to create and delete documents, you'll also need to write the document identifier to the document management record type. If you do not write the document identifier to the record type, you cannot relate or reference the document in your application.

Documents can be created and deleted alongside other application data (like an invoice for a customer) or independently (like a FAQ document shared with the entire company).

With application data

When users create or delete documents alongside other application data, the process model handles both the business data and the document identifiers. For example, users upload system logs and screenshots related to their support case.

The easiest way for users to create and delete documents alongside application data is using a process model that includes:

• A start form. This interface should allow users to create application data and upload related documents. See the following interface recipes to learn how you can create this type of start form:
  • Upload Multiple Documents in an Editable Grid.
  • Upload Multiple Documents and Edit Document Properties.
    
    
• A Delete Records node. This node should delete the document identifiers from the document management record type if any documents are removed from the start form. The document cleanup schedule will remove the document from the associated document folder.
  
  
• A Write Records node. This node should write the application data to the appropriate record type and write the document identifiers to the document management record type.

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

Without application data

This section describes how to configure interfaces and process models that allow users to create and delete a document by itself. These objects are used to create record actions on the document management record type.

You can also generate record actions on the document management record type to quickly create and configure these interfaces and process models.

Create a document

You can configure your application so that the system or a user can create a document in the following ways:

• A File Upload component in an interface.
• A Document Generation smart service.
• Receiving a binary or Base64 document through an integration.

When the document is created, it will exist in the generated document folder, but can only be accessed via the identifier in the document management record type.

The most common way to create documents is using a File Upload component.

To allow users to create a document using a File Upload component:

1. Create an interface. This is where users will upload a document.
2. Add a rule input and set the type the document management record type.
3. Add a File Upload component to the interface and configure the file upload component as follows:
   • For the Target parameter, use the recordType! domain to reference the document management record type. For example, recordType!Resource.
   • Set the value and saveInto parameters to the document field in the document management record type. For example, recordType!Resource.fields.documentId.

   Tip:  See the recipe Upload and Name a File for an example.

4. Create a process model.
5. Add a process variable that matches the rule input name and type from the interface containing the File Upload component.
6. Set the interface as the start form.

7. Add a Write Records node to write the document identifier to the document management record type.

   For example, the process model could look like this:

   

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

8. Open the document management record type.
9. Manually add the process model as a record list action.

Delete a document

If a user no longer needs a document, you can allow them to delete it with a simple record action.

When the document identifier is deleted from the document management record type, the document object still exists in Appian. These documents are automatically deleted from Appian using a clean up schedule; however, you can also manually delete the document object from your process model using the Delete Document smart service.

To allow users to delete a document:

1. Create an interface. This interface should confirm that users want to delete the document.
2. Create a process model.
3. Add a process variable and set the type to the document management record type.
4. Set the interface as the start form.
5. Add a Delete Records node. This will delete the document identifier from the document management record type.

6. (Optional) Add a Delete Document node after the Delete Records node. This will delete the document object from the generated document folder and remove the document's information from the Document record type.

   For example, the process model could look like this:

   

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

7. Open the document management record type.
8. Manually add the process model as a related action.

Monitor documents

The Documents page in your document management record type displays all the documents available in the document folder that's associated with your record type. You can quickly search, preview, and download these documents to verify them and monitor their use.

When you manage documents stored in Appian, the Documents page will display a breakdown of how much space is used to store these documents. You can use this information to determine if you need to customize or change your document cleanup schedule.

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

The breakdown includes:

• Total Documents: The total disk space used by all documents in the document folder associated with this record type.
• Referenced: The disk space used by documents associated with a record in this record type. This means that the document's identifier is written as a row in the record type, which allows you to reference the document in your applications.
• Orphaned: The disk space used by documents that are not associated with a record in this record type. Even though the document is still in the document folder, it's not accessible in your applications since there is no way to reference it.

Clean up documents

Appian automatically cleans up documents to maintain system efficiency. Your configuration options for document cleanup vary based on the document's storage location.

Clean up Appian-stored documents

When you delete data from a document management record type that manages documents stored in Appian, the physical file remains in the generated document folder. A file without an associated record is referred to as an orphaned document.

To manage orphaned documents, a default cleanup schedule is enabled for all document management record types. This process automatically deletes orphaned documents that haven't been modified within a specific timeframe. For example, if the cleanup schedule is set to 30 days, orphaned documents are deleted on day 31.

You can modify the document cleanup schedule in the following ways:

• Customize: Adjust the cleanup schedule for specific record types.
• Disable: Turn off the cleanup schedule for a record type.
• Immediate cleanup: Delete orphaned documents in bulk during testing or maintenance.
• Manual delete: Remove individual documents manually.

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

Customize the cleanup schedule

If a record type manages large files, you may want to delete unused orphan documents from that record type more frequently than the default cleanup schedule allows.

To customize the document cleanup schedule on a record type:

1. In the record type, go to Documents.
2. Go to the Configurations tab.
3. Under Automatic Document Cleanup, select Custom Settings.
4. For Automatic Document Cleanup, keep Yes selected.
5. For Delete After Number of Days, enter the number of days after which an unused orphaned document will be deleted. For example, if you enter 10 days, then orphaned documents that have not been modified in the last 10 days will be deleted on day 11.
6. For Start Cleanup At, select when to start the automatic cleanup.
7. Click SAVE.

Disable the cleanup schedule

If you need to keep all documents that have been uploaded, even those that are no longer needed, you can disable document cleanup.

To disable document cleanup on a record type:

1. In the record type, go to Documents.
2. Go to the Configurations tab.
3. Under Automatic Document Cleanup, select Custom Settings.
4. For Automatic Document Cleanup, select No.
5. Click SAVE.

Immediately clean up documents

If you need a one-time cleanup to remove a batch of orphaned documents, you can start an immediate document cleanup.

To start an immediate document cleanup:

1. In the record type, go to Documents.
2. From the List tab, click CLEAN UP DOCUMENTS.
3. For Delete Orphaned Documents Older Than (Days), enter the number of days after which unused orphaned documents will be deleted.
4. Click CLEANUP.

Any documents older than the specified number of days will be immediately deleted.

Manually delete documents

While automatic document cleanup will delete documents without associated records after a certain number of days, you may want to immediately delete an unused document when you're testing your app.

To manually delete one or more documents:

1. In the record type, go to Documents.
2. From the List tab, select the checkbox next to the documents you want to delete.
3. Click DELETE.

Clean up externally-stored documents

Appian temporarily stores external documents to improve performance and enable common document activities like extraction and classification. Appian automatically deletes these documents on a regular schedule.

The cleanup schedule depends on the method used to access the document.

Access Method	Cleanup Schedule
Viewed in an interface from a Document Viewer, Document Download Link, or Document Image component	After 24 hours
Retrieved from the Return External Documents smart service	After 30 days

Feedback