Share saved queries and changes with your team

Team sharing needs Firetool Pro, for reading a shared file as well as for writing one. Each person on the team uses their own licence and their own Google account.

What you can share

Saved queries (and JS Query scripts), saved changes, dashboard cards, expected schemas, bookmarks and User 360 setups. Only how each one is set up goes into the file: the project, the collection, the filters, the script. Your accounts, keys, query history, Firetool's settings and your documents never go in. There is no Firetool server: the file lives where your team already keeps such things, such as a git repository, OneDrive, Google Drive or a network drive.

Filters and scripts can hold values such as a customer's email address, so keep the file somewhere only your team can open.

Share items once

1. Open the ★ panel in the sidebar and click ⇪ (Share with your team), or press Ctrl+K and type Share with your team.
2. Enter your name. Colleagues see it beside each item you share.
3. Tick what to share and click Save file…. Firetool writes firetool-shared.json where you choose.

To take a colleague's file in, click ⇩ (Import shared items…) in the same panel. Each item shows who shared it, its project, the account of yours that will open it, and whether it is new or updates one you already have. An item that can't be used here says why, for example when none of your accounts can open its project. Tick what you want and click Import.

Nothing you import runs by itself. A saved change opens its usual dialog with the preview, and a script waits for you to press Run.

Keep one shared file in step

Instead of passing files around, the team can keep one shared file that everyone's Firetool reads and saves into.

1. Open Settings → Team.
2. The first person clicks New shared file… and saves it in the shared folder. Everyone else clicks Use a shared file… and picks that file.
3. Click Share more… and then Save to the team file to put your items in it.

Firetool reads the file when it starts, when you come back to it and every 3 minutes, and only when the file has changed. Settings → Team shows where you stand:

• New from the team: items you haven't taken in yet. Take in… opens the import list with them.
• Changed here: items you changed on your computer since they were saved to the team. Save to the team saves them.
• Changed here and in the team file: yours isn't replaced. Choose Use the team's or Save mine.
• From this computer: how many of your items are in the file, Share more… and Remove from the team….

When a colleague saves a newer version of an item you took in or shared, and you haven't changed it, the new version arrives by itself and Firetool tells you. If the file isn't there (the drive isn't connected, say), nothing on your computer changes and Settings → Team says so.

Remove from the team… takes items out of the file for everyone. They stay on your computer, and colleagues who took them in keep their copies as their own. Stop using forgets the file and leaves it where it is.

When two people change the same item

Firetool never writes over the file. Each save reads it again, merges your items into what is there and only then replaces it, so a colleague's work saved a moment earlier is kept. The newer version of an item wins. If two people changed the same version of an item at the same time, both versions are kept, the later one with (copy) at the end of its name, and Firetool tells you so. Keep the one you want and remove the other.

Firetool won't write into a file that isn't a Firetool shared file, and it says so when the folder is read-only for you.

Scripts from colleagues

The first time you run a JS Query script that came from the team, Firetool asks: This script was written by <name>. Run it? Read it first: a script can change data. It runs with your account, your role and the project's rules, and its changes go in the audit log, as any script does. Firetool asks only before the first run on your computer, and not at all once you've changed the script yourself.

Saving to the team and removing from it are recorded in the audit log too, with the items' IDs and kinds but not their contents.

For IT: set the file or turn sharing off

The machine policy can hold two settings for team sharing:

{
  "sharedFile": "%USERPROFILE%\\OneDrive - Your Company\\Firetool\\firetool-shared.json"
}

"sharedFile" sets the team file for everyone. ~, %NAME% and ${NAME} become each person's own folders and environment, so one policy fits everyone's OneDrive. Settings → Team then shows the file as set by your IT team, without Choose another or Stop using. "team": false turns team sharing off: Share, Import and Settings → Team say so, and what people took in before stays on their computers.

From the terminal and git

The firetool command reads and checks the shared file, and merges two versions of it:

# The items in the team file chosen in Settings → Team (or --file <path>)
firetool shared list
# Exit code 6 when an item can't be used: a CI step for the repository that holds the file
firetool shared check --file firetool-shared.json
# Two versions as one, as Firetool merges them
firetool shared merge ours.json theirs.json --out merged.json

When the file is kept in a git repository, let git merge it the same way, so two branches that both changed it merge without conflict markers:

# .gitattributes in the repository
firetool-shared.json merge=firetool

# once on each computer
git config merge.firetool.driver "firetool shared merge %A %B"

Questions

Related

• Features: what's new in 4.5.
• Saved changes and scripts: make the changes you share.
• Query Firestore: saved queries and the dashboard.
• Roles and production safety: what still applies to shared items.