Setting Up External SFTP Connections

Configure Modalius to send and receive files with your partners via their external SFTP server.

Information You Need

Before setting up an external SFTP connection, get the following from your partner:

Step 1: Create Credentials

First, store your partner's SFTP credentials securely:

1. Navigate to Connections & Routing in the sidebar
2. Click the Credentials tab
3. Click Add Credential
4. Enter the credential details:
   • Name - A descriptive name (e.g., "Partner SFTP Credential")
   • Note - Optional description
   • Username - The SFTP username
   • Password/Key - The password or private SSH key
   • Expiration - Optional expiration date (you will be notified before expiration)
5. Click Save

Step 2: Create the Connection

Next, create the SFTP connection using those credentials:

1. Navigate to Connections & Routing in the sidebar
2. Click Add Connection
3. Select SFTP as the connection type
4. Enter the connection details:
   • Connection Name - A display name for this connection
   • Connection URL - The server address (e.g., sftp://sftp.partner.com:22)
   • Credentials - Select the credential you created in Step 1
   • Trusted Host Key - Optional; paste the server's SSH host key for security verification (will be auto-learned during testing if not provided)
   • Session Limits - Optionally restrict the number of simultaneous active sessions
5. Click Save

Host Key Management

When setting up or editing an external SFTP connection, you can view and manage the server's SSH host key for security verification. Host keys ensure you are connecting to the correct server and protect against man-in-the-middle attacks.

• Providing a host key during setup: If your partner provides a host key (e.g., ssh-ed25519 AAAAC3...), paste it into the Trusted Host Key field during connection creation. Modalius will validate it on every subsequent connection.
• Auto-learning: If no host key is provided, Modalius will automatically learn and store the key during the first successful test or connection attempt.
• Updating a host key: If your partner rotates their server's host key, you can update it by editing the connection. Open the connection, click Manage > Edit Configuration, and paste the new key in the Trusted Host Key field.

Configuring Polling Frequency

For inbound connections where Modalius needs to check an external SFTP server for new files, you can configure the polling frequency. This sets how often Modalius connects to the partner's SFTP server to look for new files.

1. During connection creation, click Add Polling Limit in the External SFTP Settings section
2. Enter the polling interval in minutes (minimum: 1 minute)
3. To remove polling, click the delete icon next to the Polling Frequency section

You can also adjust the polling frequency after creation by editing the connection from the connection detail page (Manage > Edit Configuration).

Step 3: Test the Connection

After saving, test the connection to verify it works:

1. Open the connection you just created
2. Click Manage > Test Connection
3. Wait for the test to complete
4. Review the result

Test Results:

If a trusted host key was not provided, Modalius will automatically learn and store it during the first successful test.

Step 4: Add Routing Rules

Configure how files should be routed through this connection:

1. Open the connection details
2. Go to the Routing Rules tab
3. Click Add a Routing Rule
4. Configure the rule:
   • Direction - Inbound (receive) or Outbound (send)
   • Sender / Receiver Business Unit - Which business unit this rule applies to
   • Directory Path - Remote folder for file delivery
   • Filename Pattern - Optional filter for specific files
   • Transaction Types - Optional filter by EDI transaction type
   • Priority - Determines the order rules are evaluated when multiple rules match
5. Click Save

Enabling and Disabling Connections

Connections can be temporarily disabled without deleting them. This is useful during partner maintenance windows or when you need to pause file delivery.

To disable a connection:

1. Open the connection detail page
2. Toggle the Enabled switch off, or use Manage > Disable Connection
3. Choose how to handle incoming files while disabled:
   • Ignore incoming files - Files received while the connection is disabled will be ignored
   • Queue files while inactive - Incoming files will be stored and automatically delivered once the connection is re-enabled
4. Click Disable Connection to confirm

To re-enable a connection: Toggle the Enabled switch back on, or use Manage > Enable Connection. If you chose to queue files, all queued files will begin delivering automatically.

Troubleshooting Common Issues

Connection Health Monitoring

Modalius continuously monitors your external SFTP connections:

• Health indicators show current connection status on the connection detail page
• Automatic recovery - When a connection goes down, Modalius automatically tests it periodically until it recovers
• File queueing - Files are queued during outages and automatically delivered when the connection recovers
• Activity history - View detailed logs of all connection attempts and their results in the Activity Log tab

Connection Detail Tabs

When you open an external SFTP connection, the detail page provides several tabs for managing the connection:

• Routing Rules: View, add, and delete routing rules that control how files flow through this connection. Each rule specifies a direction, business unit, directory, and optional filters.
• Queue: View files currently waiting in the delivery queue for this connection, including filename, size, queued time, and status.
• Activity Log: View a history of connection activity, including test results, delivery attempts, and status codes.
• Configuration History: View a log of all changes made to this connection over time.