File Sharing

Files and folders residing on accsyn storage volumes can be shared with other users, either through a delivery or through the accsyn file sharing engine.

Documentation: https://support.accsyn.com/file-sharing

An accsyn share is the base entity for the following storage entities available through the API:

  • Volume; The base directory where accsyn has access and files can be shared or delivered. Users with the employee role have full access to volumes granted to them; restricted users do not.
  • Folder; A shared folder beneath a volume at a relative path. Restricted users receive access through ACLs (access control lists).
  • Home; A shared folder designated to a user, providing a default file access area. Home folders are optional, but accsyn can be configured to create one automatically on user activation.
  • Collection; A virtual shared folder containing one or more files and/or folders, with access granted through ACLs to standard users.

Working with volumes

List volumes

To list all volumes:

volumes = session.find('Volume')

A list of dictionaries will be returned containing volume attributes:

{
    "code": "projects",
    "created": "2024-05-20T17:34:14",
    "creator": "demo.admin@accsyn.com",
    "default": true,
    "description": "Huvudvolym f\u00f6r projekt.",
    "email": "",
    "id": "664b6d76e43eb396e5e55419",
    "licensed": true,
    "metadata": {},
    "modified": "2026-02-02T07:13:12",
    "modifier": "backend@accsyn.com",
    "name": "Projects",
    "path": "/Volumes/projects",
    "paths": {
        "linux": "/projects",
        "mac": "/Volumes/projects",
        "windows": "P:"
    },
    "queue": null,
    "status": "enabled",
    "type": "volume"
}

Explanation of the returned attributes:

  • code: The unique API name of the share.
  • created: Date of creation.
  • creator: The user that created the share.
  • default: true if this is the default (main) volume for temp deliveries and home shares. Only one main volume can be defined; if none is set, the first volume defaults to main.
  • description: Volume description.
  • email: Additional email addresses to deliver notifications to.
  • id: The internal accsyn job id, use this when modifying the share later on.
  • licensed: (Internal) true if the volume is licensed, false if not.
  • metadata: Volume metadata dict, used to transport data with workflows.
  • modified: Date of last modification.
  • modifier: The user who most recently modified the share.
  • name: The name of the volume.
  • path: When served by a server, this will be the resolved absolute path on storage for this volume.
  • paths: Dict of path definitions per supported operating system (Windows, Linux, macOS). May also include VPN paths so the desktop app can correctly identify remote source/destination and download/upload mode.
  • type: The share type, always “volume”.
  • status; The status of share, see below.

Volume statuses

Volume statuses:

accsyn volume statuses
Code: Description: Writeable 1:
enabled Normal state - volume is enabled and functioning. YES
disabled Volume is disabled - all related jobs are put on hold. YES
offline Volume is enabled but unavailable — not served or the folder on the server is missing. Related jobs are put on hold.  
disabled-offline Volume is offline and disabled. Related jobs are put on hold.  
  • 1 This status can be set with a volume modify call (see below)

Create a volume

To create a volume, supply its name, server ID and paths (admin role required):

volume = session.create("Volume",{
    "name":"Assets",
    "code":"assets",
    "paths":{
        "windows":"A:",
        "windows_vpn":"\\192.168.0.1\assets",
        "linux":"/assets",
        "linux_vpn":"/192.168.0.1/assets",
        "mac":"/Volumes/assets",
        "mac_vpn":"/net/192.168.0.1/assets",
    },
    "server": "664b5db8ed9dc749a06f9bd6",
    "siteservers": ["6751d72886f229f292b4f2d4"]
})

Note

  • The API identifier “code” must be unique with the workspace among all shares.
  • The path corresponding to the operating system server is running must be supplied.
  • The siteservers list of IDs are optional.

Modifying a volume

Rename a volume

To rename a volume:

session.update("Volume", "61779c54b80099ea066b0604", {"name":"Assets 2"})

A dictionary is returned in the same format as a volume query.

To change the API code identifier:

session.update("Volume", "61779c54b80099ea066b0604", {"code":"assets2"})

To update the paths:

session.update("Volume", "61779c54b80099ea066b0604", {"paths":{"windows":"B:","linux":"/assets2","mac":"/Volumes/assets2"}})

List servers

To list which servers are serving a volume:

retval = session.assignments("Volume", "61779c54b80099ea066b0604")

Return value will be a list of dictionaries with assignment data.

Assign server

To change which server is serving a volume on the main site (hq) (admin role required):

retval = session.assign("Volume", "server", {
    "volume":"61779c54b80099ea066b0604",
    "server": "66867188e8b00e18156bcf51"
})

Return value will be True if operation was successful. Ongoing jobs will not be affected by this change, only new jobs.

Note

  • The server must be authenticated with an admin user account to serve volumes.
  • All file transfer endpoints are called clients in accsyn. A server is a client role that listens for incoming TCP connections from remote P2P clients.

To assign a site server, e.g. a server that will serve a volume locally at a remote office/cloud location:

retval = session.assign("Volume", "server", {
    "volume":"61779c54b80099ea066b0604",
    "server": "66867188e8b00e18156bcf51"
})

Return value will be True if operation was successful. Ongoing jobs will not be affected by this change, only new jobs.

Note

The server must be configured to be at this site before this command can succeed.

De-assign server

To stop a server from serving a volume, call the ‘deassign’ API function (admin role required):

retval = session.deassign("Volume", "server", {
    "volume":"61779c54b80099ea066b0604",
    "server": "66867188e8b00e18156bcf51",
})

Return value will be True if operation was successful. Ongoing jobs will not be affected by this change, new jobs will not be able to be submitted until a new server is assigned for the volume.

Note

  • If the server is at main site (hq) and it is the default volume, accsyn delivery and home shares might stop functioning until a new server is assigned.

Granting access to a volume

Users with the employee role have no default volume access. Access must be granted through ACLs (Access Control Lists).

Note

The backend ACL entity is not directly exposed through the API. ACLs are also used internally — for example, to bind users to deliveries.

To grant access to an employee, use the session assign function:

acl = session.grant("User", "61779c54b80099ea066b0604", "Volume", "664b6d76e43eb396e5e55419")

Return value will be a dictionary with same form as the access list query would return.

List volume access

To list ACLs for a volume:

acl = session.access("Volume", "664b6d76e43eb396e5e55419")

Return value will be a list of dictionaries containing selected ACL attributes.

Revoke access to a volume

To revoke access to a volume:

acl = session.revoke("User", "61779c54b80099ea066b0604", "Volume", "664b6d76e43eb396e5e55419")

Return value will be true if operation was successful. False will be returned if the user did not have access to the volume.

Delete a volume

To delete a volume:

session.delete_one("Volume", "61779c54b80099ea066b0604")

Return value will be True if operation was successful.

Note

  • If you delete a volume, all associated jobs are aborted.
  • All associated shared folders and homes will be deleted.
  • All associated ACLs will be deleted.
  • No files or folders on disk will be touched.

Working with shared folders and homes

An accsyn shared folder/home is a folder beneath a volume, designated to be shared with one or more users through ACLs (Access Control Lists).

List folders

To query shared folders:

shared_folders = session.find('Folder')

A home is similar to a shared folder, but bound to a user and optionally created automatically on user activation. To query homes:

homes = session.find('Home')

A dict will be returned containing share attributes:

{
    "code": "theproject",
    "created": "2024-11-19T16:49:33",
    "creator": "demo.employee@accsyn.com",
    "description": "",
    "email": "",
    "id": "673cb38dea344d0d17969018",
    "metadata": {},
    "modified": "2026-02-04T13:10:25",
    "modifier": "demo.admin@accsyn.com",
    "name": "TheProject",
    "parent": "664b6d76e43eb396e5e55419",
    "parent_hr": "share:Projects[volume](664b6d76e43eb396e5e55419)",
    "path": "projects/TheProject",
    "queue": null,
    "status": "enabled"
}

Explanation of the returned attributes:

  • code: The unique API identifier of the share. Used in accsyn path notation: “share=<code>/some/path”.
  • created: Date of creation.
  • creator: The user that created the share.
  • description: Share description.
  • email: Additional email addresses to deliver notifications to.
  • id: The internal accsyn share id, use this when modifying the share later on.
  • metadata: Share metadata dict.
  • modified: Date of last modification.
  • modifier: The user who most recently modified the share.
  • name: The name of the share.
  • parent: The ID of the parent volume.
  • parent_hr: Human readable parent volume entry.
  • path: The relative path share has beneath parent volume.
  • queue: The queue (ID or code) to put jobs in, when involving this share. Will have no effect if queue already defined for job.
  • status; The status of share, see below.

Shared folder/home states

Shared folder/home statuses:

accsyn share statuses
Code: Description: Writeable 1:
enabled Normal state - share is enabled and functioning. YES
disabled Share is offline and disabled - all related file transfers are put on hold. YES
offline Share is enabled but the volume is offline - no server, missing or have other issues.  
disabled-offline Share is offline and disabled — all related file transfers are put on hold.  
  • 1 This status can be set with a modify call (see below)

Create a shared folder

To share a folder beneath a volume, provide the parent (volume) ID, the relative path to the folder and the name of the share (employee clearance required):

share = session.create("Folder",{
    "parent": "664b6d76e43eb396e5e55419",
    "path":"projects/theproject",
    "name":"Shared project assets",
})

In both cases, if creation was successful, a dictionary will be returned on the same format as a share query would return.

Create a home

To create a home share, you can either create it like a shared folder or just supply the user ID or email address(code):

home = session.create("Home", {
    "user": "693bf3168d4e0d0c2afe1d53",
})

A dictionary will be returned containing home attributes on the same format as a folder query would return.

Note

  • The user will not be automatically granted access to the home, access must be granted through ACLs (see below).

Granting access to a shared folder/home

A shared folder or home is not automatically accessible to any user, access must be granted through ACLs (Access Control Lists).

To grant access to a user, use the session assign function:

acl = session.grant("User", "61779c54b80099ea066b0604", "Folder", "673cb38dea344d0d17969018", {
    "path": "FROM_VENDORS/acmevfx",
    "read": True,
    "write": True,
    "notify": True,
    "message": "Please upload your files here.",
})

Return value will be a dictionary containing ACL attributes.

Note

  • The path is relative to the shared folder/home. If omitted, the entire folder is granted (equivalent to path: "/").
  • Either read or write access must be granted; both cannot be false.
  • The notify flag is optional, and defaults to True. If set to False, no email will be sent to the user when the ACL is granted.
  • The message is optional, and will be sent as a notification to the user when access is granted.

List ACLs

To list ACLs for a volume folder:

acls = session.access("Volume", "61779c54b80099ea066b0604")

Return value will be a list of dictionaries containing ACL attributes.

List all ACLs beneath a volume, including shared folders and homes:

acls = session.access("Volume", "61779c54b80099ea066b0604", recursive=True)

To list ACLs for a shared folder:

acls = session.access("Folder", "673cb38dea344d0d17969018")

Revoke access to a shared folder/home

To remove an ACL, use the session deassign function:

acl = session.revoke("User", "61779c54b80099ea066b0604", "Folder", "673cb38dea344d0d17969018")

Return value will be True if operation was successful, false if the user did not have access to the folder.

Modify a shared folder/home

To disable a share:

session.update("Folder", "614d660de50d45bb027c9bdd", {"status" :"disabled"})

Configuring a queue which will become default for new jobs using share:

session.update("Folder", "614d660de50d45bb027c9bdd", {"queue" :"5ac60a8b1da7ee7eb4d146cf"})

Working with collections

A collection is a virtual shared folder containing one or more files and/or folders to be granted access through ACLs to one or more standard users. The files can stem from multiple source volumes, folders and/or homes.

To create a collection, you need to supply the source volumes, folders and/or homes IDs. In this example we are adding files both from a separate volume (assets) and a shared folder (theproject) on a default volume:

collection = session.create("Collection", {
    "name": "Project startup",
    "files": ["volume=assets/ASSETS/templates/vendor_structure", "folder=theproject/admin/theproject-specs-v1.2.doc"],
})

A dictionary will be returned containing collection attributes on the same format as a folder query would return.

Note

  • The file paths cannot be absolute, they have to be on accsyn format and point to a file on a volume, folder or home.

List files in a collection

To list files in a collection:

files = session.find("File", parent="698452ee3bce6dbca4b68619")

Return value will be a list of dictionaries containing file attributes.

Add files to a collection

To add a file to a collection:

session.create("File", {
  "files":[
    "share=theproject/ref/mp_ref.tif"
  ]
}, collection["id"])

Return value will be a dictionary containing file attributes on the same format as a file query would return.

Remove files from a collection

To remove a file from a collection:

session.delete_many("Collection", "698452ee3bce6dbca4b68619", {
  "files":[
    "12d89033-2a8c-4029-992b-3a02b4ecc2cd"
  ]
})

Return value will be True if operation was successful, false if the file did not exist in the collection.

Deactivate

A share (volume, folder, collection) can be deactivated — removed from accsyn but eligible for audit and restore if you recreate a share with the same name:

session.deactivate_one("Volume", "61779c54b80099ea066b0604")

Note

  • Deactivating a volume also causes all descendant shares to be archived.
  • No active jobs may use the share; abort them first.
  • ACLs are offlined with the share.
  • Inactive shares have the attribute inactive set to True.
  • Home shares cannot be deactivated, deactivate the user instead.

Re-activate a share

To re-activate a share, supply the user email address(code) or ID:

session.activate_one("Volume", "61779c54b80099ea066b0604")

Delete

To delete a share:

session.delete_one("Folder", "61779c54b80099ea066b0604")

Note

  • Deleting a share is preceded by deactivation.
  • For audit/security reasons, deleted shares with associated data (acls) are kept in the archive for deep audit.