Default SFTP Integration with KnowledgeCity

Summary

The Default SFTP integration allows KnowledgeCity to exchange data with external systems using a secure FTP (SFTP) connection — without requiring a direct API integration from the external side.

It supports three core flows:

• Import users into KnowledgeCity from an SFTP inbox
• Export course completions from KnowledgeCity to an SFTP destination
• Export course catalog data from KnowledgeCity to an SFTP destination

All operations can be scheduled to run automatically on a daily or weekly basis.

Introduction

The purpose of this integration is to enable automated, file-based data exchange between KnowledgeCity and an external system through a secure SFTP connection. It allows admins to:

• Automatically provision and update users in KnowledgeCity from HR or directory systems that produce CSV exports
• Push course completion records to external reporting or compliance systems via SFTP
• Share the KnowledgeCity course catalog with external platforms in CSV format

This is ideal for organizations that do not have a direct REST API integration available but can exchange files over SFTP on a schedule.

Requirements

Before setting up the Default SFTP integration, confirm the following prerequisites:

Admin Permissions

• You must have Administrator access in the KnowledgeCity LMS to enable and configure integrations.

KnowledgeCity API Access

• A valid KnowledgeCity API Base URL and API Secret are required. It is recommended to create a dedicated user for the integration and use that user’s API Secret.
• Use api.knowledgecity.com for standard portals, or api-sa.knowledgecity.com for RB and MENA portals.

SFTP Server Details

You must have the following SFTP connection details ready for each export/import destination:

• SFTP Host
• SFTP Port
• SFTP Username
• SFTP Private Key (base64-encoded)
• Target path (for exports) or Inbox/Received paths (for imports)

Note: The private key file content must be base64-encoded before pasting into the configuration. You can use an online base64 encoder to convert your key file.

CSV File Format Readiness

• For User Import: the source CSV file must have column headers that you will map to KnowledgeCity user fields (e.g., UserLoginName mapped to username).
• For Exports: you will define the column titles and their order in the configuration.

Steps to Follow

1) Enable the Default Integration

• Log in to the KnowledgeCity LMS as an Administrator.
• Go to the Integrations page.
• Find the Default Integration card.
• Click Enable and make sure the top-level Turn On checkbox is checked.

Important: The top-level Turn On is a master switch. If it is unchecked, all child-level settings (exports and import) will be ignored by the system, regardless of their individual settings.

2) Configure KnowledgeCity API Settings

Under the KnowledgeCity API section, fill in:

• Base API URL: The KnowledgeCity API base URL with version (e.g., https://api.knowledgecity.com/v1)
• API Secret: The API secret of the dedicated integration user

Save your changes.

3) Configure Course Completion Export (Optional)

To export course completion records from KnowledgeCity to your SFTP server:

• Expand Export Setup and check Turn On.
• Expand Export Course Completion and check Turn On.
• Set the export file name pattern (use [date]Ymd[/date] in the name to auto-insert the export date).
• Set the export date format for the begin date and passed date fields (leave blank to export as Unix timestamp).
• Define the CSV Fields: specify column titles and their order in the output file.

Under the FTP Destination sub-section:

• Check Turn On.
• Fill in your SFTP connection details: host, port, username, and base64-encoded private key.
• Set the Target path (relative or absolute) where the generated file will be transferred.

Under Schedule Setup:

• Check Turn On and configure daily or weekly recurrence.

4) Configure Course Export (Optional)

To export the KnowledgeCity course catalog to your SFTP server:

• Under Export Setup, expand Export Courses and check Turn On.
• Set the export file name pattern.
• Define the CSV Fields: specify column titles and their order.

Under the FTP Destination sub-section:

• Check Turn On and fill in your SFTP connection details and Target path.

Under Schedule Setup:

• Check Turn On and configure the desired recurrence.

5) Configure User Import (Optional)

To import users from a CSV file on your SFTP server into KnowledgeCity:

• Expand Import Setup and check Turn On.
• Expand Import Users and check Turn On.
• Under CSV Fields, map the column headers from your import file to KnowledgeCity user fields (e.g., UserLoginName → username).

Under Metadata Handling, configure the import behavior:

• Autoassign licence: Assign the first available license to imported users (ignored if Subscription ID is specified)
• Subscription ID: Assign a specific subscription to imported users
• Assign license on user update: Also attempt to assign a license to existing users during updates
• Enable simulation mode: Dry-run mode for testing; no data will be written to KC
• Default group name: Add new users to a default group if not specified in the import file
• Succeed job on duplicate new user: Continue with a warning instead of failing if a duplicate user is detected
• Activate and assign license to disabled user on update: Re-enable and license a user that was previously disabled
• Skip user if exists on add_update action: Create new users but skip existing ones
• Assign Subscription by Group Name: Map subscriptions to specific group names
• Include/Exclude fields by action: Control which fields apply for add vs. update actions
• Required fields: Specify fields that must be present for add actions

To disable users not present in the import file, check Turn On under Disable users not in the list and configure:

• Always disable or Disable when keyword is found in file name
• Minimum rows: Safety threshold to prevent accidental mass-disabling from small or test files

Under the FTP Source sub-section:

• Check Turn On and fill in your SFTP connection details.
• Set the Inbox path (where the system looks for new files) and Received path (where processed files are moved after download).

Under Schedule Setup:

• Check Turn On and configure the desired recurrence.

Expected Result

Successful Connection and Sync

• Integration is enabled and the KnowledgeCity API credentials are validated.
• SFTP connection is verified for each enabled export/import section.

Course Completion Export (if enabled)

• A CSV file with completion records is generated and transferred to the configured SFTP target path on the defined schedule.
• File name includes the export date when the [date]Ymd[/date] pattern is used.

Course Export (if enabled)

• A CSV file with course catalog data is generated and transferred to the configured SFTP target path on the defined schedule.

User Import (if enabled)

• New CSV files found in the SFTP inbox are downloaded and processed.
• Users are created, updated, reactivated, or deactivated in KnowledgeCity based on the import configuration.
• Processed files are moved from the inbox to the received path.

Troubleshooting