DemoClient | Developer Portal for YouTrack and Hub Documentation

Import Client Lifecycle

How YouTrack uses an import client:

Loads the import script package and calls exports.Client(context) to create a client instance.
Passes connection parameters, secrets, and settings through the context object.
Calls prepareToImport() when the client defines initialization logic.
Requests projects, users, groups, issues, articles, attachments, and other entities through the methods implemented by the client.
Calls update methods during continuous import to fetch changes since the previous import.

For a guided walkthrough of the built-in demo package, see Demo Import Script. For the end-to-end import flow, see How Import Scripts Work.

Required and Optional Methods

Method	Status	Purpose
`exports.Client(context)`	Required	Returns the client instance that YouTrack calls during import.
`constructor(context)`	Required for class-based clients	Reads import parameters, prepares credentials, and creates reusable connections.
`prepareToImport()`	Optional	Runs startup checks or caches source metadata before YouTrack starts reading entities.
`getServerInfo()`	Recommended	Returns source version and time information for diagnostics and import logs.
`getProjects()`	Required for project import	Lists projects that can be imported from the source system.
`getProject(projectInfo)`	Required for project import	Returns full project data for a selected source project.
`getIssues(projectInfo, after, top)`	Required for issue import	Returns one page of issues for a project.
`getUsers(group, skip, top)`	Required when users or groups are imported	Returns users for a group or page of users requested by YouTrack.
`getArticles(projectInfo, after, top)`	Optional	Returns one page of articles for a project.
`getAttachmentContent(project, document, attachment)`	Optional	Returns binary content and metadata for attachments referenced by imported entities.
`getLinkTypes()`	Optional	Returns link type definitions used by imported issues.
`getTimestampFormats()`	Optional	Lists date and date-time formats that the importer can parse from source data.
`getUserTimeZoneId()`	Optional	Defines the time zone used when source timestamps do not include one.

Pagination Contract

Parameter	Used by	Expected behavior
`after`	`getIssues`, `getArticles`	Start reading after the item or cursor from the previous page.
`top`	Page-based read methods	Return no more than this number of entities.
`updatedAfter`	Continuous import update methods	Return only entities changed after this timestamp.

Continuous Import Methods

Continuous import uses update methods to fetch changes after the initial import. Implement these methods when the source can expose reliable update timestamps or change streams.

Method	Use it to
`getIssueUpdates(projectInfo, after, updatedAfter, top)`	Return changed issues for a project since the previous synchronization.
`getArticleUpdates(projectInfo, after, updatedAfter, top)`	Return changed articles for a project since the previous synchronization.

HTTP Connection Setup

A client that reads from a web API usually creates a reusable HTTP connection in the constructor. For details about the HTTP module, see http.

Minimal Client Skeleton

Start with the smallest client that can list projects and issues, then add optional methods as the source data requires. For instructions on editing and running custom scripts, see Working with Import Scripts.