Skip to main content

​
Overview

Central Management

Makes FTP/SFTP/FTPS access consistent across all Integration Flow steps by keeping Connection definition central.

Automatic Authentication

Shortens configuration time by reusing automatic authentication and SSL/TLS parameters in Connector steps that perform file transfer.

Security

Reduces data leakage risk by ensuring access only to authorized folders with working directory (workingDir) restriction.

Retry

Increases transfer success even in unstable networks thanks to retry (retryCount) and timeout values.

Environment-Based Management

You can perform Test Connection with environment selection; you can use ${var} syntax in fields such as host, port, username, password with Environment Variable support.

Connection Initialization

When FTP/SFTP/FTPS connection is requested from within Integration Flow or Connector, the system reads configured connection parameters.

Authentication

Access to target FTP directory is provided with username and password. SSH key-based authentication is not supported.

Data Communication

File upload/download, listing, or deletion operations are performed at TCP layer via selected protocol.

Connection Management

When operation is completed, session is closed.

Error Management

In case of connection error, timeout, or authentication error, defined retryCount comes into play, result is written to deployment logs.

Partner File Receipt

Downloading files coming from partner systems at certain intervals

Bulk Report Upload

Regular upload of bulk report or log files to FTP servers

SFTP Financial Data

Integration with external services sharing financial data via SFTP

FTPS Regulation

Institution connections with mandatory encrypted transfer requirement with FTPS (Explicit) due to regulation

Legacy System Integration

Using Legacy file transfer servers in internal network in Integration Flow steps

​
Technical Features and Capabilities

Multiple Protocol Support

FTP, SFTP, and FTPS protocols can be selected under single connection definition.

Working Directory Isolation

Directory that connection can access is limited with workingDir field.

Retry Policy

Automatic retry is provided in network interruptions with retryCount.

Environment-Based Configuration

Environment selection is required for Test Connection; environment variables are resolved per environment.

Enable/Disable Control

Making Connection active or passive (enable/disable toggle). In passive state, connection cannot be used but its configuration is saved.

Implicit / Explicit FTPS Key

How TLS handshake will be performed is determined with useImplicit and useExplicit flags.

Dynamic Project or Global Positioning

Connection can be kept within project or made accessible in all projects with Move to Global.

Import Up to 100 MB

FTP connection definitions up to 100 MB size can be imported in ZIP import operations.

Connection Test Feature

Ability to verify connection parameters before saving with “Test Connection” button. Environment selection is required for test.

Export/Import Feature

Exporting Connection configuration as ZIP file. Importing to different environments (Development, Test, Production). Version control and backup capability.

Environment Variable Support

You can use environment variables with ${variableName} syntax in host, port, username, password, workingDir, and sslProtocol fields.

​
Connection Parameters

Name

Description: Connection name (must be unique)
Example Value: Production_FTP
Notes: Should not start with space, special characters should not be used

Host

Description: FTP/SFTP server address
Example Value: ftp.partner.local
Notes: IPv4/IPv6 or FQDN accepted

Port

Description: Port where protocol runs
Example Value: 21
Notes: 22 recommended for SFTP, 990 for FTPS

Username

Description: Username on target server
Example Value: partner_sync
Notes: Should be created according to least privilege principle

WorkingDir

Description: Initial working directory
Example Value: /outbound
Notes: Relevant user must have access permission

Protocol

Description: Transfer protocol to be used
Example Value: FTP / SFTP / FTPS
Notes: Selected from EnumFtpProtocol list

Timeout

Description: Connection timeout (seconds)
Example Value: 30
Notes: Value is in seconds

RetryCount

Description: Retry count
Example Value: 3
Notes: Specifies how many retries will be made in network interruptions

SSL Protocol

Description: Version to be used in FTPS handshake
Example Value: TLS
Notes: Required when using FTPS

Password

Description: User password or environment variable reference
Default Value: (Empty)
Recommended Value: Environment variable usage with ${variableName} syntax

UseImplicit

Description: Activates FTPS implicit handshake
Default Value: false
Recommended Value: true (in environments requiring FTPS implicit)

UseExplicit

Description: Activates FTPS explicit STARTTLS process
Default Value: true
Recommended Value: true (default; can be set to false in scenarios other than FTPS)

​
Usage Scenarios

Partner File Receipt

Situation: Supplier uploads XML every night
Solution: WorkingDir=/inbox, Protocol=SFTP, RetryCount=5
Expected Behavior: Night job downloads files securely

Regulation FTPS Transfer

Situation: Bank system requires FTPS implicit
Solution: UseImplicit=true, Port=990, SSL Protocol=TLS1.2
Expected Behavior: TLS handshake succeeds, files are encrypted

Legacy FTP Push

Situation: Old system only supports FTP
Solution: Protocol=FTP, Port=21, Timeout=45
Expected Behavior: Gateway performs upload via classic FTP

Large File Transfer

Situation: Long-running transfers
Solution: Timeout=90, chunk upload in Flow
Expected Behavior: No disconnection in long transfers

Disaster Recovery

Situation: Parallel copy sent to DR environment
Solution: Environment=Production, Host=dr-ftp.local or via environment variable
Expected Behavior: Main and DR systems are kept synchronized

Security Scan

Situation: SOC team pulls logs via SFTP
Solution: Environment=Test, Protocol=SFTP, WorkingDir=/audit
Expected Behavior: Only audit folder is accessed

​
Connection Configuration

​
Creating New FTP Connection

Image 2024 9 9 15 35 35 Pn

​
Configuration Steps

1

Going to Creation Page

  • Go to Connection → FTP Connection section from left menu.
  • Click [+ Create] button in top right.
2

Entering Basic Information

Enable Status (Active Status):
  • Set active/passive status with toggle. New connections are active by default.
Name (Name) - Required:
  • Example: Production_FTP
  • Enter unique name, should not start with space.
  • System automatically checks. Green checkmark: available. Red X: existing name.
Description (Description):
  • Example: “Partner FTP uploads”
  • Max. 1000 characters.
  • Describe the purpose of Connection.
3

Environment Selection

  • Select environment from dropdown menu: Development, Test, or Production.
  • Environment selection is required for Test Connection.
4

FTP Specific Parameters - Part 1

  • Host & Port: Enter target FTP address, set port according to protocol.
  • Protocol: Select FTP, SFTP, or FTPS.
  • WorkingDir: Write full path of folder to be accessed.
  • Username/Password: Enter username and password. You can select variable from Variable button and paste for environment variable.
5

FTP Specific Parameters - Part 2

  • UseImplicit / UseExplicit: Select FTPS handshake type.
  • SSL Protocol: Specify TLS version (e.g., TLS1.2).
  • Timeout: Set between 30-90 seconds according to network delay.
  • RetryCount: 3-5 recommended for unstable connections.
6

Security and Authentication Settings

  • Use username/password or environment variable.
  • Load necessary certificates to trust store for FTPS (if using FTPS).
  • Warning: Do not allow anonymous FTP access in Production environment.
7

Test Connection

  • Click [Test Connection] button.
  • Ensure environment is selected.
  • Test whether connection parameters are correct.
  • Successful: Green confirmation message
  • Failed: Error details are shown
8

Saving

  • Click [Save and Deploy] button in top right.
Checklist:
  • Unique name
  • Required fields filled
  • Test connection successful (recommended)
Result:
  • Connection is added to list
  • Becomes available for use in Integration Flow and Connector steps
  • Becomes active according to environment
Connection created successfully! You can now use it in Integration Flow and Connector steps.

​
Deleting Connection

To delete a connection:

Method 1: From List Screen

  • From ⋮ menu at end of row in connection list, select Delete.
  • Confirm deletion in the confirmation dialog.

Deletion Tips

Check Before Deleting:
  • May be used in Integration Flow or Connector steps.
  • Assign alternative connection if necessary.
  • Backup with Export before deleting.

Alternative: Deactivate

  • Instead of deleting, set connection’s active status to passive.
  • Connection becomes passive but is not deleted.
  • You can reactivate and reuse when needed.

​
Exporting/Importing Connection

In this step, users can export (export) existing connections for backup, moving to different environments, or sharing purposes, or import (import) a previously exported connection again. This operation is used to maintain data integrity in version control, transitions between test and production environments, or inter-team sharing processes.

Method 1: From List Screen

  • From ⋮ menu at end of row in connection list, select Export.
  • ZIP file is automatically downloaded.

File Format

Format: {Date}-ftp-integration-{ConnectionName}-export.zip
Example: 13 Nov 2025-ftp-integration-Production_FTP-export.zip

ZIP Contents

  • Connection JSON file
  • Metadata information
  • Dependency information (e.g., certificates, key store)

Usage Areas

  • Backup
  • Moving between environments (Test → Prod)
  • Versioning
  • Team or project-based sharing

Import Steps

  • Click [Import FTP Connection] button on main list.
  • Select downloaded ZIP file.
  • System checks: Is format valid? Is there name conflict? Are dependencies present?
  • Then click [Import] button.

Import Scenarios

Scenario 1: Name Conflict → Overwrite old connection or create with new name.Scenario 2: Missing Dependencies → Create missing certificates or key stores first or exclude during import.

​
Usage Areas of Connection

Creating and Activating Connection

Steps:
  1. Create Connection
  2. Verify connection with Test Connection
  3. Save and activate with Save and Deploy
  4. Ensure Connection is in Enabled status

Usage in Integration / Connector Steps

Connection is selected in steps requiring file transfer with FTP/SFTP/FTPS protocol. Example: “FTP Read File”, “FTP List File” steps. Connection selection is performed from Connection field in step configuration. Same connection can be reused in both file sending and receiving steps.

Scheduled Job Usage

Connection is selected in scheduled tasks (e.g., file receiving/sending at certain intervals, log archiving) to access FTP/SFTP servers. When connection changes, job behavior is updated accordingly.

Test Purpose Usage

Connection Test feature allows verifying connection correctness independently from Integration Flow. This test is critical in debugging process.
Test results are not guarantee of production transfer; test Integration Flow separately

​
Best Practices

Working Directory Management

Bad: Giving user root directory access
Good: Only giving permission to necessary folder
Best: Defining separate workingDir for each scenario and limiting with ACL

Credential Management

Bad: Storing password as plain text in form
Good: Storing sensitive information using environment variable
Best: Using ${var} references with Variable button

Protocol Selection

Bad: Using default FTP in every environment
Good: Selecting SFTP or FTPS when needed
Best: Managing protocol by environment and mapping with security requirement

Environment Management

Bad: Using same connection parameters in all environments
Good: Creating separate connection for each environment
Best: Managing all environments in single connection using environment option, only changing environment during inter-environment transitions

Connection Test

Bad: Saving and deploying Connection without testing
Good: Verifying with Test Connection before saving
Best: Testing after each parameter change, performing full integration test in test environment before moving to production

IP and Firewall Restrictions

Open FTP servers only to Apinizer gateway IP range, whitelist passive FTP port range if necessary

File Integrity

Catch unexpected manipulations by performing checksum verification after transfer

Credential Management

Store sensitive information such as username and password using environment variable. Do not hardcode credentials in code or configuration files. Update passwords periodically

SSL/TLS Usage

Always enable SSL/TLS in Production environment. Use self-signed certificates only in development environment. Track certificate expiration dates and renew on time

Access Control

Allow only authorized users to change Connection configuration. Store Connection change logs. Apply change approval process for critical connections

Anonymous FTP Usage

Why to avoid: Authentication is bypassed, data leakage occurs
Alternative: Define users with mandatory credentials

Wide-Permission Users

Why to avoid: Unnecessary delete/write permission increases risk
Alternative: Use read-only or accounts authorized only to necessary directories

Wrong Protocol Selection

Why to avoid: Selecting FTP in environment requiring FTPS causes regulation violation
Alternative: Select SFTP/FTPS according to requirement, document protocol

Using Production Connection in Test Environment

Why to avoid: Test data may be written to production system, real users may be affected, security risk occurs
Alternative: Create separate connection for each environment, use environment parameter, separate connection names by adding prefix according to environment (Test_, Prod_)

Very Low Timeout Values

Why to avoid: Connection constantly times out in network delays, Integration steps fail
Alternative: Adjust timeout values according to real usage scenarios, measure network latency and determine timeouts accordingly

File Segmentation

Recommendation: Break large files into parts at Integration Flow level
Effect: Transfer time shortens, retry cost decreases

Passive/Active FTP Selection

Recommendation: Use passive FTP behind firewall and narrow port range
Effect: Network issues decrease, connection stability increases

Timeout Values Optimization

Recommendation: Measure real network latency, adjust timeout values accordingly, avoid very low or very high timeouts
Effect: Unnecessary waits are prevented, fast fail-over is provided, user experience improves

​
Troubleshooting

Wrong workingDir, user may not have listing permission, or firewall may be blocking passive port range.
1

WorkingDir Validation

Verify WorkingDir value.
2

User Permissions

Check FTP user permissions.
3

Passive Port Range

Open passive port range.
Wrong sslProtocol value, certificate may have expired, or UseImplicit/UseExplicit may be incompatible.
1

TLS Version

Align TLS version with other party.
2

Certificate Renewal

Renew certificate.
3

FTPS Mode

Select correct FTPS mode.
Network delay, target system responding slowly, or timeout value may be too low.
1

Network Check

Check network connectivity.
2

System Health

Check target system health.
3

Timeout Settings

Increase timeout values.
4

Log Review

Review Connection logs.
Wrong username/password, expired credentials, or permission problem may exist.
1

Credentials

Verify credentials.
2

User Status

Check that user is active in target system.
3

Permission Check

Check that necessary permissions are granted.
4

Certificate Check

Check SSL/TLS certificates.
Different connection may be selected in Integration/Connector step, step may be incorrectly configured, or Flow/Job may not have been redeployed.
1

Enable Toggle

Check that Connection’s enable toggle is active.
2

Connection Selection

Verify that correct connection is selected in Integration Flow.
3

Connection Deploy

Redeploy Connection.
4

Flow/Job Deploy

Redeploy Integration Flow or Job.
5

Log Check

Check Gateway logs.

​
Frequently Asked Questions (FAQ)

You can change protocol in same connection but creating separate environment parameters for each protocol increases traceability.
Yes, all file paths used in Flow must be updated according to new workingDir; otherwise you will get “file not found” error.
Port range is defined on FTP server, same range must be opened in firewall on gateway side. You can note this in Connection document for information purposes.
SFTP connection supports only username and password authentication. SSH key-based authentication is not supported in the current version.
Yes, as long as user permissions allow both operations; same connection can be selected in Integration Flow steps.
Yes, the same connection can be used in multiple Integration Flow or Connector steps. This provides central management and guarantees configuration consistency. However, care should be taken as changes made to connection will affect all usage locations.
Yes, it is recommended that you create separate connection for each environment. Alternatively, you can manage all environments within a single connection using environment parameter. This approach provides easier management and less error risk.
Several reasons may exist:
  1. Connection enable toggle may be passive
  2. Different connection may be selected in Integration step
  3. Connection may not have been deployed
  4. Integration Flow may not have been redeployed yet