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

Enables same connection to securely route to different endpoints with environment-based (Development/Test/Production) parameters.

Connection Initialization

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

Connection Pool Management

Gateway keeps previously opened FTP sessions in pool at gateway, project, or global level; creates new connection if suitable session does not exist.

Authentication

Access to target FTP directory is provided by performing username/password or certificate-based authentication.

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 or returned to pool and kept ready for next requests.

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

Ability to define separate connection parameters for each environment (Development, Test, Production).

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.

Export/Import Feature

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

Connection Monitoring

Monitoring connection health, pool status, and performance metrics.

​
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: Must be between 1-120 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 access token
Default Value: (Empty)
Recommended Value: Secret Manager reference

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)

​
Timeout and Connection Pool Parameters

Connection Timeout

Description: Maximum wait time for establishing connection
Default: 30000
Min: 5000 | Max: 120000
Unit: milliseconds

Request Timeout

Description: Maximum wait time for request response
Default: 60000
Min: 10000 | Max: 180000
Unit: milliseconds

Pool Size

Description: Maximum number of connections in Connection pool
Default: 10
Min: 1 | Max: 50
Unit: count

Retry Interval

Description: Wait time between retries
Default: 2000
Min: 500 | Max: 10000
Unit: milliseconds

​
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 Segmentation

Situation: 2 GB log files are transferred
Solution: Timeout=90, Pool Size=20, 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, UseExplicit=false
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.
  • Different connection parameters can be defined for each environment.
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 optional password or leave empty and use credential store.
5

FTP Specific Parameters - Part 2

  • UseImplicit / UseExplicit: Select FTPS handshake type.
  • SSL Protocol: Specify TLS version (e.g., TLS1.2).
  • Deploy to Worker: Keep active if you want connection to be kept on worker.
6

Timeout and Connection Pool Settings

  • Timeout: Set between 30-90 seconds according to network delay.
  • RetryCount: 3-5 recommended for unstable connections.
  • If necessary, Request Timeout and Pool Size values are customized in Integration Flow step.
7

Security and Authentication Settings

  • Pull username/password or SSH key from secret manager.
  • Load necessary certificates to trust store for FTPS.
  • Warning: Do not allow anonymous FTP access in Production environment.
8

Test Connection

  • Click [Test Connection] button.
  • Test whether connection parameters are correct.
  • Successful: Green confirmation message
  • Failed: Error details are shown
9

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

Deletion Operation

Select Delete from ⋮ menu at end of row or click [Delete] button on connection detail page

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

Use Disable option instead of deleting. Connection becomes passive but is not deleted. Can be reactivated 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

Select ⋮ → Export from action menu. ZIP file is automatically downloaded.

Method 2

Click [Export] button on Connection detail page. ZIP file is downloaded.

File Format

Format: Date-connection-FTP Connection-export.zip
Example: 13 Nov 2025-connection-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

FTP/SFTP selection is made in steps like “Upload File”, “Download File”, “Read Directory”. 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

File receiving/sending is performed at certain periods in scheduled tasks. When Cron changes, job immediately uses relevant connection parameters

Test Purpose Usage

“Test Connection” result is saved in logs, serves as reference in troubleshooting 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: Keeping password in Secret Manager and referencing
Best: Using SSH key or Vault-based dynamic credentials

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

Monitoring and Alarm

Bad: Not tracking RetryCount increases
Good: Moving pool and timeout metrics to dashboard
Best: Defining alarm thresholds and creating automatic incidents

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

SFTP Key Management

Keep SSH keys in secret store
Do not share same key in different projects

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 or secret manager. 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

Not Using Connection Pool

Why to avoid: New connection opens on each request, performance decreases, resource consumption increases, target system load increases
Alternative: Enable Connection pool, adjust pool size according to traffic volume, set up pool monitoring

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

SFTP Cipher Setting

Recommendation: Select fastest but secure cipher package with server (e.g., aes128-gcm)
Effect: CPU load and delay decrease

Connection Pool Optimization

Recommendation: Adjust pool size according to peak traffic (recommended: concurrent request count × 1.5), set idle connection timeouts, perform pool health check
Effect: Connection opening cost decreases by 80%, response times decrease, resource usage is optimized

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

Connection Monitoring

Recommendation: Monitor Connection pool usage, track timeout rates, perform connection health check, set up alerting
Effect: Problems are detected proactively, performance bottlenecks are identified early, downtime decreases

​
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.
Pool size may be too low, connection leak may exist, or traffic may be too high.
1

Pool Size

Increase pool size.
2

Connection Check

Check that connections are properly closed.
3

Idle Timeout

Set idle connection timeouts.
4

Metric Monitoring

Monitor Connection usage metrics.
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.
You can store it as Base64 in secret manager and reference it in authentication section of Integration Flow step, use without changing connection parameters.
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.
Connection pool usage is not mandatory but strongly recommended in high-traffic systems. Reusing existing connections instead of opening new connection on each request significantly increases performance.
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