Return External Document Smart Service

Overview

The Return External Document smart service retrieves a document from an external system using a record.

While record types can access and manage external documents, you cannot retrieve the actual file using the a!queryRecordType() function. Instead, you should use this smart service when you need to pass the document to:

• Process models
• AI skills
• Expression rules

Requirements

• Required Object: A record type with a document download integration configured.
• Required Permission: The node executer needs at least Viewer permissions for the record type.

Properties

• Category: Document Management
• Icon:

• Assignment Options: Unattended

• Compatible with autoscale: Yes

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
Record	Any Type	The record for the document. This record should be provided as a value that contains the record type and the identifier.	Yes	No
Pause on Error	Boolean	Determines if the node should pause or continue if an error occurs (default: true). If set to continue when an error occurs, the error information can be retrieved from the output of the smart service.	No	No

Node outputs

Name	Data Type	Description
Document	Document	Returns the document from the integration.
Success	Boolean	Returns true if the integration successfully returned the document or false if it failed.
Error Message	Text	When applicable, the error message returned by the integration.

a!returnExternalDocument()

The Return External Document 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.

a!returnExternalDocument( record, onSuccess, onError )

Parameters

Keyword	Type	Description
record	Any Type	The record for the document. This record should be provided as a value that contains the record type and the identifier.
onSuccess	Any Type	A list of saves to execute after the integration executes successfully. Created with a!save(). The result returned by the integration is available in the function variable fv!result.
onError	Any Type	A list of saves to execute after the integration does not execute successfully. Created with a!save(). The result returned by the integration is available in the function variable fv!result. The error returned by the integration is available in the function variable fv!error.

Usage considerations

Referencing the record

To return an external document, you must pass a single record that includes both the record type and the record identifier. This smart service does not support passing a list of records.

You can pass a record using a:

• Process variable.

  For example, pv!customerDocument, where the type is set to the Customer Document record type.

• Rule inputs.

  For example, ri!customerDocument, where the type is set to the Customer Document record type.

• Record type constructor.

  For example:

  1
  2
  3
  4
  recordType!RE Customer Document(
    recordType!RE Customer Document.fields.id: 1,
    recordType!RE Customer Document.fields.documentId: 190656
  )
  

Automatic document cleanup

When you use this smart service, the files are temporarily stored in Appian to improve performance and enable common document activities, like extraction and classification. Appian automatically deletes these documents after 30 days.

Possible errors

The node may fail to execute in any of the following scenarios:

• The record type doesn't have a document download integration configured.
• The integration fails to return the document.
• You provide a list of records instead of a single record.

Example: Classify an external document

The Financial Document record type manages the metadata for financial files stored in an external system. Each file can be a different document type, like an invoice or purchase orders. The company wants to automatically classify these documents so they can create accurate financial dashboards.

In this example, the Return External Document smart service retrieves a file so that an AI skill can classify it and update the record type.

Prerequisites

To follow this example, you need:

• A document management record type (such as the Financial Document record type).
• A published document classification AI skill.

Create the process model

The following process model retrieves an external file, classifies it, maps the result to a record field, and updates the Financial Document record type.

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

To create this process model:

1. Create a form to allow users to select a document for classification.
2. In the form, save the document selection to a rule input that points to the Financial Document record type (for example, ri!financialDocument).

3. In the process model, create the following process variables:

   Name	Type	Parameter?
   financialDocument	Financial Document (Record Type)	Yes
   file	Document (Data Type)	No

4. Add a Return External Document node and configure the following:
   • Input: Pass the specific financial document using pv!financialDocument.
   • Output: Save the retrieved file to pv!file.
5. Add a Classify Documents node and configure the following:
   • Input: Pass the retrieved file using pv!file and set your confidence threshold.
   • Output: For AboveThreshold, BelowThreshold, and Failed, click New process variable to automatically create process variables for these outputs. Use the new process variables to configure each of the Targets.
6. Add a Script Task node and configure the following:
   • Output: Click + New Custom Output and configure an expression that maps the classified results to the value you want to store in the record type. Set the Target to the appropriate field in the record type (for example, financialDocument.docType).
7. Add a Write Records node and use the pv!financialDocument variable as the Records Input to write the new classification to the record type.

Feedback