File Transfers

An accsyn file transfer job 1 defines a set of file(s) and/or folder(s) to transfer from one endpoint (client) to another, using either the ASC protocol or HTTPS (web transfer).

1 Job is a generic term within accsyn, covering transfers, deliveries, compute, etc.

Query

To list all active transfers:

transfers = session.find('Transfer')

This returns a list of active file transfer jobs as dict objects that the session has permission to read.

A dict will be returned containing transfer job attributes:

{
    "code": "README.txt",
    "created": "2026-01-22T08:35:59",
    "destination": "user:6676f3e9c7ef4e27da254e57",
    "destination_hr": "user:lisa@example.com[standard](6676f3e9c7ef4e27da254e57)",
    "etr": "",
    "finished": "2026-01-22T08:43:05",
    "id": "6971e16fceadd67b955b1995",
    "name": "README.txt",
    "progress": 0,
    "size": 0,
    "source": "workspace:6645fbca9f8c4d3e7a3b678d",
    "source_hr": "workspace:seagull(6645fbca9f8c4d3e7a3b678d)",
    "speed": -1.0,
    "status": "aborted",
    "user": "6676f3e9c7ef4e27da254e57",
    "user_hr": "user:lisa@example.com[standard](6676f3e9c7ef4e27da254e57)"
}

Explanation of the returned attributes:

  • code: Same as name, transfers and jobs in general do not have unique API identifiers.
  • created: Date of creation.
  • destination: The recipient, in the form <entitytype>:<id>.
  • destination_hr: The recipient, in human-readable form.
  • etr: (Running transfers) Estimated time remaining.
  • finished: The date the job finished — completed or aborted.
  • id: The internal accsyn job id, use this when modifying the job later on.
  • name; The name of the job, if no name supplied a name will be generated from the first source filename.
  • progress: The job total progress, an integer in the range 0 to 100.
  • size: The total size of job, in bytes.
  • source: The sender, in the form <entitytype>:<id>.
  • source_hr: The sender, in human-readable form.
  • speed: The current transfer speed, in MB/s.
  • status: The status of job.
  • uri: The job URI within queues, built from parent queue code attributes.
  • metadata: Job metadata dict, used to pass user data through workflows.
  • parent: The id of the parent job queue.
  • parent_hr: The parent job queue, in human-readable form.
  • user: The id of the user that created the job.
  • user_hr: The user who created the job, in human-readable form.
  • modified: Date of last modification.
  • modifier: The user that most recently modified the job.

Job statuses

Transfer job statuses:

accsyn transfer job statuses
Code: Description: Writeable 1:
init Job is newly created and is initialising, total file size is measured.  
waiting Job is blocked and waiting for resources to become available, for example jobs ahead in queue or a server/client coming online / getting enabled. YES
running Job is working, files are being transferred or compute tasks are executed.  
paused Job is put on hold. YES
failed Job has failed for some reason and might retry automatically at a later point, check logs for clues.  
aborted Job has been aborted. YES
done Job is done executing all its tasks. YES
  • 1 This status can be set with a modify call (see below)

Job queries

Retrieve a job by name (code), using quotation marks for whitespace in the query:

transfer = session.find_one('Transfer WHERE name="x and y.png"')

Note

If no match is found, None is returned.

Multiple jobs can share the same name — ensure names are unique or query by ID.

To pretty-print a job and its attributes, use Session.dump():

print(session.dump(transfer))

To list all jobs spawned by a certain user:

session.find_one('Transfer WHERE user=user@mail.com')

Or jobs having a certain destination (<user>, <site>):

session.find_one('Transfer WHERE destination=stockholm')

List all downloads - jobs having main site “hq” (default code) as source:

session.find_one('Transfer WHERE source=hq')

Finished transfers

When a transfer is finished or aborted, it is not live anymore and will not be returned by standard queries. To retrieve finished jobs, supply the ‘finished’ attribute:

session.find('Transfer WHERE status=aborted', finished=True)

After default two weeks/14 days, inactive jobs are purged and archived. To retrieve jobs from the archive, supply the ‘archived’ attribute, recall that this operation may take long time to execute:

session.find('Transfer WHERE status=done', archived=True)

To return a single job, regardless if it is finished or archived, use the get_entity function:

transfer = session.get_entity("Transfer", transfer_id)

Create

When creating a file transfer, source and destination must be specified with full paths.

Example: submit a transfer where a user downloads a file from a shared folder to their local machine:

transfer = session.create("Transfer",{
    "source":"share=myproject/delivery/TRAILER_screening_v003.mov",
    "destination":"/Volumes/EDIT/from_client",
    "status":"paused"
})

If successful, transfer job data is returned in the same form as a query.

Note

The term share is a generic identifier for volume, folder (shared folder), collection, or home.

This example assumes the user has one online accsyn client (desktop app or user server). If the user has multiple clients, specify which one — for example: "destination":"client=664f53b16aa9149860da9d9c:/Volumes/EDIT/from_client".

For a complete set of job submit examples, see: https://support.accsyn.com/job-specification.

Modify

To resume or abort a transfer:

session.update("Transfer", '614d660de50d45bb027c9bdd', {'status':"waiting"})
session.update("Transfer", '614d660de50d45bb027c9bdd', {'status':"aborted"})

Delete

To delete a Transfer:

session.delete_one("Transfer", "614d660de50d45bb027c9bdd")

Tasks

A task is a file or directory to transfer within a job. Task access through the API is restricted — for example, deleting tasks or changing their paths is not supported. To skip a task, set its status to excluded.

Query tasks

Job tasks are a sub-entity of a job, not a standalone accsyn entity. To query tasks, supply the parent job ID separately from the query:

tasks = session.find("Task", entityid="5a7325f8b7ef72f5f9d74bf4")

Find all tasks that have a certain status:

tasks = session.find("Task WHERE status=onhold", entityid="5a7325f8b7ef72f5f9d74bf4")

A list of tasks is returned as dictionaries:

{
    "created": "2020-08-04T09:52:27",
    "destination": {
        "client": "5da09b9ae1b3c330746529ec",
        "path": "/Users/tommy/Downloads/A001_C011_09187Ia.mov",
        "path_abs_final": "/Users/tommy/Downloads/A001_C011_09187Ia.mov",
        "user": "5d91b33ac71c12871d1fc3c2"
    },
    "finished": "2020-08-04T10:12:26",
    "id": "26468234-c9ee-48d6-8d28-e900b5957129",
    "job": "69732302fd379c8fff1089d0",
    "job_hr": "README.txt[7](6971e16fceadd67b955b1995)",
    "priority": 1,
    "size": 128868496,
    "source": {
        "client": "5da08873b0eb10fade60b3f7",
        "path": "A001_C011_09187Ia.mov",
        "path_abs_final": "X:\A001_C011_09187Ia.mov",
        "v": "5c5bf52a1da7ee0165105b85",
        "user": "5d91b33ac71c12871d1fc3c2"
    },
    "status": "queued",
    "time": 110239,
    "uri": "0",
}
  • created: The date of task creation.
  • destination: Dictionary containing information about the destination file/directory party.
  • finished: The date task finished execution.
  • id: The internal accsyn ID of task.
  • job: The ID of the parent job.
  • job_hr: The parent job, in human-readable form.
  • priority: The task priority, see job priority.
  • size: The size of source file/directory.
  • source: Dictionary containing information about the source file/directory (or compute client) party.
  • status: Task status (see below). Values include pending (waiting for user to choose download location), queued, booting, executing, failed, done, onhold, and excluded.
  • time: Time taken to execute this task.
  • uri: The task URI — a unique name/code, usually a sequential number ("0", "1", etc.) in string format.

The contents of source and destination vary depending on whether the party is a site (server) or user (desktop app/user server):

  • client: The ID of the client.
  • path: The file path, either absolute if no share is involved or relative share (folder, collection, volume etc.)
  • path_abs_final: The final evaluated path when a share is involved. Set at transfer execution, as clients may apply dynamic path resolvers at runtime.
  • v: ID of the volume.
  • s: ID of the share, if a share is involved.
  • user: ID of the user, if party is a user.
  • site: ID of the site, if party is a site.

Note

  • If no user or site is involved, the party is the workspace main site and server (hq).
  • source and destination cannot be modified.
  • time is the time to execute the entire bucket (group) of tasks as dispatched, not the individual task.
accsyn task statuses
Code: Description: Writeable 1:
pending Task(job) is newly created and waiting for receiving user to select a download path.  
queued Task is waiting to be dispatched. YES
booting Task transfer/execution is being initialised on involved parties.  
executing File/directory is being transferred or task is being executed(compute)  
failed The task has failed for some reason, check job log and/or task log for clues. YES
onhold Task is on hold. YES
excluded Task is excluded from execution. YES
done File/directory has been transferred / compute task has executed successfully. YES
  • 1 This status can be set with a modify call (see below)

Create tasks

Add a file(task) to an existing job, mirroring paths to same destination as rest of job:

session.create("Task", {"tasks":["/Volumes/projects/creatures_showreel_2018.mov"]}, job["id"]))

Returns {“success”:True} if everything goes well, exception thrown otherwise. If another task exists with the same source and destination, no task is added and the existing task is retried instead. To reject duplicate tasks, pass allow_duplicates=False to the create call.

Note

Tasks without a destination can only be created on jobs that send files with mirrored paths.

Add a single task to a download job:

session.create("Task", {
  "tasks":{
    "source":"_REF/creatures_showreel_2018.mov",
    "destination":"/Users/johndoe/Downloads/creatures_showreel_2018.mov"
  }
}, entityid=transfer["id"])

The single task will be returned as a dictionary, providing task ID, status and other attributes. If adding multiple tasks, a list of tasks will be returned.

Note

  • Only users themselves own the right to add files from/to their local harddrive/storage for upload/download.
  • Operation will fail if another task exists with same source and destination path
  • Ongoing executing tasks will not be interrupted when new tasks are added.

Modifying tasks

Only the status, priority or metadata attributes of a task can currently be modified.

Tasks are always updated in group with values supplied as a list of dicts instead of a single dict:

transfer = session.find('Transfer where id=5a7325f8b7ef72f5f9d74bf4')

updated_tasks = session.update_many("Task", transfer["id"], [{
    "id":"cc5f2afa-9ae4-46e0-9273-82ac802b20ff",
    "status":"onhold"
}])

Will return the updated tasks, as would have been returned by a task find query.

Delete task

Tasks cannot be deleted for audit and security reasons. Set task status to excluded to skip it during transfer/execution.