Free cookie consent management tool by TermsFeed

Set Up the Appian Adapter for Swift

On This Page
This content applies solely to Appian Adapter for Swift, which must be purchased separately from the Appian base platform. This content was written for Appian 26.3 and may not reflect the interfaces or functionality of other Appian versions.

The Appian adapter for Swift orchestrates the validation, transformation, and routing of messages between your internal applications, upstream financial systems, and external Swift networks. After installing the Appian adapter for Swift, configure it to work for your organization.

After installing the adapter, complete the following steps to integrate with your upstream and downstream systems:

  1. Configure the inbound message flow.
  2. Configure the outbound message flow.
  3. Set up pre-validation.
  4. Configure Swift Case Management integration.
  5. Configure Swift gpi Tracker integration.
  6. Set up BIC directory integration.
  7. Configure environment constants.
  8. Configure user groups and security.

Note:  The adapter sits as an intermediary between your core business applications (downstream systems) and your financial networks or external gateways (upstream systems). Upstream systems include financial networks, message queues, or external gateways handling raw Swift messages. Downstream systems include your internal business applications such as Appian applications, ERPs, or case management tools that process structured data objects.

Caution:  Updates in Appian Designer must be done with caution by someone familiar with Appian development.

Configure the inbound message flow

The adapter accepts incoming Swift messages from upstream systems, validates them against compliance standards, transforms them into structured Appian data objects, and sends them to downstream systems.

To enable this flow:

If any of your systems are inflexible, you can build connector modules to sit between the adapter and your upstream or downstream systems to support the integration.

The Appian adapter for Swift is currently configured to enable one downstream system that receives all inbound messages. You can build a routing engine in the downstream connector, or create a decision point directly within your instance of the adapter to support multiple downstream tools.

Objects to configure for inbound messages

The following objects require configuration for the inbound message flow:

Object Type Action
SMM Inbound Message Connected System Connected System Clear out the value of the API key and provide the actual key generated by the downstream system. You can also choose another authentication method.
SMM_URL_SEND_INBOUND_MESSAGE_ENDPOINT Constant Set this constant to the endpoint for the service from your downstream system.
SMM Finalize Inbound Message Processing Process Model (Optional) Add a decision point in this process model to send your messages to various downstream systems. If you take this approach, you need a connected system and a constant like the two above for each downstream system.
SMM Receive Inbound Swift Message Web API The API that upstream systems call to send messages to the adapter. Use the Web API Authentication page in the Admin Console to configure authentication and access. Generate an API key and a corresponding service account for each external system that requires access to this API. After authentication is configured, add the newly created service account to the SMM Users group. You may use the same API key and service account for the adapter's other APIs.

Objects for reference for inbound messages

The following object is relevant to the inbound message flow but does not require configuration:

Object Type Purpose
SMM_PostInboundMessage Integration The integration object the adapter uses to send processed inbound messages to the downstream system.

Configure the outbound message flow

The adapter accepts structured data from your downstream applications, transforms it into a standard Swift message string, validates it, and pushes it to your designated upstream destination.

To enable this flow:

Like the inbound flow, connector modules can be used to support this outbound flow. The Appian adapter for Swift is currently configured to enable one upstream system that receives all outbound messages. You can build a routing engine in the upstream connector, or create a decision point directly within your instance of the adapter to support multiple upstream tools.

Objects to configure for outbound messages

The following objects require configuration for the outbound message flow:

Object Type Action
SMM Outbound Message Connected System Connected System Clear out the value of the API key and provide the actual key generated by the upstream system. You can also choose another authentication method.
SMM_URL_SEND_OUTBOUND_MESSAGE_ENDPOINT Constant Set this constant to the endpoint for the service from your upstream system.
SMM Call Outbound Message Integration Process Model (Optional) Add a decision point in this process model to send your messages to various upstream systems. If you take this approach, you need a connected system and a constant like the two above for each upstream system.
SMM Receive Outbound Swift Message Web API The API that downstream systems call to send outbound requests. Use the Web API Authentication page in the Admin Console to configure authentication and access. Generate an API key and a corresponding service account for each external system that requires access to this API. After authentication is configured, add the newly created service account to the SMM Users group. You may use the same API key and service account for the adapter's other APIs.

Objects for reference for outbound messages

The following object is relevant to the outbound message flow but does not require configuration:

Object Type Purpose
SMM_PostOutboundMessage Integration The integration object the adapter uses to send converted outbound messages to the upstream system.

Set up pre-validation

To optimize transaction success rates, the adapter provides a synchronous "dry-run" endpoint. Downstream systems can test messages against the adapter's validation engine before attempting actual outbound transmission.

You can embed a validation checkpoint into your user interface or business workflow (for example, right before a user clicks Submit or during an automated pre-flight check) that calls the transform and validate API. See the Appian adapter for Swift API Reference for the endpoint specification. If the API returns a successfully validated message, the business user can submit the outbound message.

Objects to configure for pre-validation

The following object requires configuration for pre-validation:

Object Type Action
SMM Transform and Validate Outbound Message Web API The API that downstream systems call to validate an outbound request. Use the Web API Authentication page in the Admin Console to configure authentication and access. Generate an API key and a corresponding service account for each external system that requires access to this API. After authentication is configured, add the newly created service account to the SMM Users group. You may use the same API key and service account for the adapter's other APIs.

Configure Swift Case Management integration

The adapter facilitates case lifecycle management by executing requests to various Swift Case Management APIs. These requests should be initiated by the downstream systems via the Swift Case Management request API, which is flexible enough to support multiple case types and actions. See the Appian adapter for Swift API Reference for the endpoint specification.

The Swift Case Management request API supports a validation-only mode that checks a request for errors and returns the result without submitting it to Swift Case Management. See the Appian adapter for Swift API Reference for the validateOnly field and validation-only response fields.

The adapter supports the following types of actions:

  • Query/Read action to search and get the details of one or more existing cases in Swift Case Management.
  • Create/Update/Write action to create or update cases in Swift Case Management.

To leverage this feature:

  • Configure triggers within your case workflows to sync data with Swift.
  • Establish a recurring job to poll cases from Swift Case Management by performing the query action for each case type you may receive.
  • Perform a create or update action after a business event occurs.

The Appian adapter for Swift ships with the capability to support OAuth 2.0 JWT Bearer Grant Type authentication with Swift Case Management. You may also opt to build an intermediary proxy server to route all traffic from the adapter to the Swift APIs. If implemented, this proxy must expose the exact same endpoint schemas as the official Swift Case Management APIs and handle all network-level authentication, certificate handshakes (mTLS), or token exchanges required by Swift.

The adapter also provides the capability of generating the request header X-SWIFT-Signature for the Swift Stop and Recall API. This header acts as a digital cryptographic signature that authenticates your application and guarantees the integrity of the payment or investigation message being sent.

Configure the Secure Credential Store

As a system administrator, you must configure the Secure Credential Store needed to create the JWT token for authentication and the X-SWIFT-Signature header attribute when sending requests to the Swift Case Management Stop and Recall API:

  1. Go to Admin Console > Third-Party Credentials.
  2. Click Create.
  3. In the Identiy > Name field, enter swiftCaseManagementKeystore.
  4. Verify that the generated Key is in lowercase.
  5. In the Plug-ins List, search for and add JWT and SWIFT Message Module Plugin [Year].
  6. In the Credentials grid, add the following details:
    1. Field name: appianprivatekeypassword Value: Password protecting the private key.
    2. Field name: appianprivatekey Value: Copy the PEM private key obtained from the Swift Developer Site for the Swift Sandbox or from Swift Certificate Center for a production environment. The private key is encrypted and never exposed by Appian.
    3. (Optional) Select Mask to mask the Value in the Admin Console and in the Third-Party Credentials settings page for end-users.
  7. Click SAVE.

Objects to configure for Swift Case Management

The following objects require configuration for the Swift Case Management integration:

Object Type Action
SMM Swift Case Management - Basic Auth Connected System Enables the adapter to retrieve an OAuth token from Swift. Update the Base URL, Username (the Swift Consumer Key), and Password (the Swift Consumer Secret) to match your Swift credentials.
SMM_SWIFT_CASE_MANAGEMENT_BASE_URL Constant Update this value to match the Base URL entered in the connected system above.
SMM_GENERATE_XSWIFT_SIGNATURE Constant Set to true to generate the x-swift-signature in real time based on the private key configured in the Admin Console. Set to false to ignore this header attribute.
SMM_SWIFT_CASE_MANAGEMENT_PUBLIC_KEY_FOR_JWT Constant Update this value to the public key required to sign the JWT. The public key is obtained from the Swift Developer Site (for the Swift Sandbox) or from Swift Certificate Center for a production environment.
SMM Receive Case Manager Request Web API The API that downstream systems call to make a request to Swift Case Management. Supports various case types and actions. Use the Web API Authentication page in the Admin Console to configure authentication and access. Generate an API key and a corresponding service account for each external system that requires access to this API. After authentication is configured, add the newly created service account to the SMM Users group. You may use the same API key and service account for the adapter's other APIs.
SMM_SCM_SERVICE_URL_CCNR_CREATE Constant Endpoint path for CCNR create requests. Default: /swift-casemanagement-ClaimNonReceipt/v7/claim-nonreceipt-investigations-requests. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_CCNR_QUERY Constant Endpoint path for CCNR query requests. Default: /swift-casemanagement-ClaimNonReceipt/v7/claim-nonreceipt-investigations. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_CCNR_UPDATE Constant Endpoint path for CCNR update requests. Default: /swift-casemanagement-ClaimNonReceipt/v7/claim-nonreceipt-investigations-responses. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_UTAP_CREATE Constant Endpoint path for UTAP create requests. Default: /swift-casemanagement-UnableToApply/v7/unabletoapply-investigations-requests. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_UTAP_QUERY Constant Endpoint path for UTAP query requests. Default: /swift-casemanagement-UnableToApply/v7/unabletoapply-investigations. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_UTAP_UPDATE Constant Endpoint path for UTAP update requests. Default: /swift-casemanagement-UnableToApply/v7/unabletoapply-investigations-responses. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_RQFI_CREATE Constant Endpoint path for RQFI create requests. Default: /swift-casemanagement-RequestForInformation/v7/requestforinformation-investigations-requests. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_RQFI_QUERY Constant Endpoint path for RQFI query requests. Default: /swift-casemanagement-RequestForInformation/v7/requestforinformation-investigations. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_RQFI_UPDATE Constant Endpoint path for RQFI update requests. Default: /swift-casemanagement-RequestForInformation/v7/requestforinformation-investigations-responses. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_INV_ACTION_CREATE Constant Endpoint path for Investigation Action create requests. Default: /swift-casemanagement-Investigation-Action/v7/investigations-actions. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_GSRP_CANCELLATION Constant Endpoint path for GSRP cancellation requests. Default: /swift-apitracker-gsrp/v6/payments/{uetr}/cancellation. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_GSRP_CANCELLATION_STATUS Constant Endpoint path for GSRP cancellation status requests. Default: /swift-apitracker-gsrp/v6/payments/{uetr}/cancellation/status. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_GSRP_CHANGED_CANCELLATION_QUERY Constant Endpoint path for GSRP changed cancellations query. Default: /swift-apitracker-gsrp/v6/payments/changed/cancellations. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_GSRP_CANCELLATION_PARTIES_QUERY Constant Endpoint path for GSRP cancellation parties query. Default: /swift-apitracker-gsrp/v6/payments/{uetr}/cancellations/parties. Update only if routing through a proxy.
SMM_SCM_SERVICE_URL_GSRP_CANCELLATION_DETAILS_QUERY Constant Endpoint path for GSRP cancellation details query. Default: /swift-apitracker-gsrp/v6/payments/{uetr}/cancellations. Update only if routing through a proxy.

Configure Swift gpi Tracker integration

The adapter sends status updates and transaction queries to the Swift gpi Tracker API on behalf of your downstream systems. Downstream systems submit these requests through a single Web API, which selects the gpi Tracker service to call based on the request payload. The adapter builds the gpi-compliant request and the integration performs the HTTP call to Swift.

The adapter supports the following gpi Tracker services:

  • Status updates for:
    • Customer Credit Transfer (CCT)
    • Cover payment (COV)
    • Financial Institution Transfer (FIT)
    • Universal Confirmation (UC)
    • Payment Modification (PMI).
  • Transaction queries to retrieve the details of a payment or to retrieve transactions that changed within a date range.

For the request and response structure of each service, the service list, and the gpi Tracker routing paths, see the Swift gpi Tracker section of the Appian adapter for Swift API Reference.

Unlike the Swift Case Management integration, the gpi Tracker integration does not use OAuth 2.0 JWT Bearer authentication. It uses a no-auth connected system, so there is no Secure Credential Store, keystore, or signature configuration to set up for this feature.

Objects to configure for Swift gpi Tracker

The following objects require configuration for the Swift gpi Tracker integration:

Object Type Action
SMM_SWIFT_GPI_BASE_URL Constant Set this value to the base URL of the Swift gpi Tracker API. For production, use https://api.swiftnet.sipn.swift.com. For pilot, use https://api-test.swiftnet.sipn.swift.com. The adapter appends the service-specific path to this base URL.
SMM Swift GPI Service Connected System - No Auth Connected System Update the Base URL to match the value set in SMM_SWIFT_GPI_BASE_URL. This connected system does not require credentials.
SMM Receive GPI Requests Web API The API that downstream systems call to make a request to a Swift gpi Tracker service. A single Web API handles all services. Use the Web API Authentication page in the Admin Console to configure authentication and access. Generate an API key and a corresponding service account for each external system that requires access to this API. After authentication is configured, add the newly created service account to the SMM Users group. You may use the same API key and service account for the adapter's other APIs.

Objects for reference for Swift gpi Tracker

The following objects are relevant to the Swift gpi Tracker integration but do not require configuration:

Object Type Purpose
SMM_SwiftGpi_PUTRequest Integration The integration object the adapter uses to send the status-update services (CCT, COV, FIT, UC, PMI) to the Swift gpi Tracker API.
SMM_SwiftGpi_GETRequest Integration The integration object the adapter uses to send the transaction-query services (transaction details and changed transactions) to the Swift gpi Tracker API.

Set up BIC directory integration

The adapter maintains a local cache of Business Identifier Codes (BICs) to validate inbound and outbound messages. This lookup table must be populated and updated via a file-based ingestion process.

To leverage BIC validation:

  1. Procure the comprehensive list of BICs from SwiftRef.
  2. Transfer the .csv file via Secure FTP to the designated directory whenever SwiftRef updates it monthly.
  3. The adapter ingests and parses the file, storing the data locally. Each time this process runs, the adapter deletes all existing data and replaces it with the values from the new file.

Configure the BIC Secure Credential Store

As a system administrator, you must configure the Secure Credential Store needed to connect to the SFTP server that holds the BIC files:

  1. Go to Admin Console > Third-Party Credentials.
  2. Click Create.
  3. In the Identiy > Name field, enter SwiftRefBicSftpCredentials or similar.
  4. Verify that the generated Key is in lowercase.
  5. In the Plug-ins List, search for and add SFTP Functions.
  6. In the Credentials grid, add the following details:
    1. Field name: Username Value: Username of the account to access the SFTP server.
    2. Field name: Password Value: Password of the account to access the SFTP server.
    3. (Optional) Select Mask to mask the Value in the Admin Console and in the Third-Party Credentials settings page for end-users.
  7. Click SAVE.
  8. Change the value of the constant SMM_SFTP_SCS_EXTERNAL_SYSTEM_KEY to the key of the Secure Credential Store created above. This key should be all lowercase.

Objects to configure for BIC directory

The following objects require configuration for the BIC directory integration:

Object Type Action
SMM_SFTP_SERVER_FILE_PATH Constant Update this value to the specific relative path where SwiftRef files are uploaded. This path is where the process model SFTP node scans for newly uploaded files.
SMM_SFTP_SCS_EXTERNAL_SYSTEM_KEY Constant Update this key to reflect the external system key from the Admin Console's Third-Party Credentials page used for the SFTP username and password.
SMM_SFTP_SERVER_PORT Constant Set this value to the network port used to establish the SFTP connection. Defaults to 22 if not specified.
SMM_SFTP_SERVER_HOSTNAME Constant Update this value to the domain name or IP address of the SFTP server.
SMM_START_BIC_PROCESS_MODEL Constant Update this value to TRUE for the adapter to ingest the BIC data.
SMM_BIC_PM_RECURRENCE_INTERVAL_DAYS Constant Update this value to specify the cadence for ingesting BIC data. A value of 7 would attempt to process BIC data every 7 days.
SMM_BIC_PM_RECURRENCE_INTERVAL_TIME Constant Update this value to specify the time of day at which to process the BIC data.

Objects for reference for BIC directory

The following objects are relevant to the BIC directory integration but do not require configuration:

Object Type Purpose
SMM Query BIC File Process Model Functions as the primary automated orchestrator for the SwiftRef integration. Connects to the remote SFTP server to query the designated file directory, evaluates folder contents, filters out previously processed files, and triggers the download and ingestion loop for unprocessed files.
SMM Download and Ingest Single File Helper Process Model Downloads a single BIC file before executing the ingestion process model.
SMM Ingest BIC File Process Model Processes a single BIC file document. Truncates the local database staging table, validates file headers, parses and imports the tab-delimited text data, computes record metrics, and writes the staging data into the core production table.
SMM_ER_SFTP_FileTransferConfigurations Expression Rule Defines the configuration parameters to connect to the FTP server hosting the BIC files.

Configure environment constants

Beyond individual feature setups, the following environment-specific constants can be edited within the adapter during deployment to ensure proper environmental behavior:

Constant Description
SMM_DEFAULT_SWIFT_VERSION Determines which Swift Standards Release version the adapter uses at runtime. Set to "2025" by default. To apply SR2026 standards, update this value to 2026. See Perform the Annual Standards Update for transition guidance.
SMM_BIC_DIRECTORY_DATA_SOURCE_NAME Set by default to jdbc/Appian. Update if you choose to store the BIC data in a different database.
SMM_EMAIL_TEMPLATE_RULE_NAME Reference to the rule that renders the email body for the inbound message notification email. To configure a different email body, build a new rule and update this constant.
SMM_INTEGRATION_MAX_RETRIES The number of times the adapter retries an integration before skipping it.

Configure user groups and security

Add users to the appropriate groups to enable them in the system.

The adapter includes the following user groups:

Group Description
SMM Users Basic users who can access the front-end components of the adapter. They can view all inbound and outbound messages as well as all Swift Case Management requests.
SMM Test Users Grants users access to the Sandbox site where they can test different messages and requests. From the Sandbox, users can send a message through the adapter to the downstream or upstream systems. Reserve access to this group to business admins.
SMM Administrators Technical users who have access to administer the application from the back end and view all details from the front end.

To add users to groups:

  1. Go to Appian Designer.
  2. Select the Appian Adapter for Swift application.
  3. In the Object Type list, select Group.
  4. Select the group to configure, such as SMM Users.
  5. Click ADD MEMBERS to add one or more users to a group.
  6. Click ADD.
  7. Repeat for each group.

Next steps

After completing the setup, continue with the following:

Feedback