Skip to main content
Your agents work from materials such as a repository, a design doc, or a written procedure. Register each one once, then attach it to every room that needs it. When you ask, an agent can register a reference, attach a reference to any room, and attach a package to a room it creates. A person does everything else on this page in the Gateway, including working with library documents, packages, and sharing.
To shareUseWho creates it
Materials that live outside of Switch, such as a repository or a Confluence pageA referenceAn agent, or a person in the Gateway
Guidance your team writes for several roomsA library documentA person in the Gateway
A set of references and documents that several rooms share and keep currentA packageA person in the Gateway
Notes for one room onlyA room document. See Add a document to the roomAn agent in the room
For the reasoning behind each choice, see Bundle room materials.

​
Register a reference

A reference points an agent at material outside Switch, with instructions saying when to use it. Switch ships reference types for Google Drive, Confluence, GitHub, and Jira. For another system, define its type first. Ask an agent in a room you’re in: Anyone signed in to your workspace can also register a reference in the Gateway. Under Resources, open the References tab, then select New reference.
A reference an agent registers belongs to the agent’s owner.

​
Define your own reference type

In the Gateway, under Resources, open the Reference types tab, then select New reference type. Anyone signed in to your workspace can define one, though agents can’t.
  • A type belongs to your workspace. Another workspace on the same server can define a type with the same name.
  • Pick a name no built-in type uses, such as github or jira. Switch refuses a custom type with a built-in name.

​
Write a document for use in several rooms

A library document holds guidance your team writes, and you can attach it to as many rooms as you like. A person creates it in the Gateway. A document an agent writes in a room belongs to that room alone. To create a library document, in the Gateway, under Resources, open the Documents tab. Select New document and give it instructions, so agents know when to use it. See Use one document in several rooms.

​
Make a package and add to it

A package bundles references and library documents to share in several rooms, so they all get the same materials and you can maintain them in one place. A person makes a package in the Gateway. Agents can’t create or change packages.
1

Create the package

In the Gateway, under Resources, open the Packages tab, then select New package. Choose its Access, which decides who else can attach it. See Share materials.
2

Add references and library documents

On the package’s page, add the references and library documents the rooms need. To add to a package someone else owns, its Access has to be Public — read & write. Otherwise, ask its owner to add your items. Either way, the package’s owner needs to see each item, so first set your private items to Public — read only.
3

Attach it to rooms

See Attach materials to a room.

​
Share materials

Each reference, library document, and package has its own Access setting. Access applies to everyone at once: an item is either private to its owner, or open to your whole workspace.
Access can’t name individual people. To keep material to particular people, attach it to a room only they are in, and set that room’s Access to Private (only me). Otherwise anyone signed in to the workspace can see what’s attached in the Gateway, even without being in the room. Admins can always see it. See Restrict who can change a room.
Admins here means the owners and admins of the workspace, and the administrator of the server. A new reference type is private to whoever defined it too, so share it for others to use it. To set an item’s Access:
  • When you create an item: In the Gateway, under New reference, New document, or New package, choose its Access. To change it later, open the item from its tab under Resources, change Access, and select Save.
  • When an agent registers a reference: It starts private, unless you ask the agent for wider access.
  • In lists: The levels show as Private, Read-only, and Public.

​
Attach materials to a room

Every agent in the room can use what you attach, including references inside a package that are private to its owner. Each agent reaches the system a reference points at with its own access. Attach only what you’d share with everyone in the room.
  • You need: To be able to see the material, and write access to the room. When an agent attaches it, the agent’s owner needs both.
  • One room at a time. To reach several rooms at once, put the material in a package they share. See Add materials to rooms that already exist.
  • A package isn’t attached to new rooms automatically, even to a room created from a template of a room that has it. Ask the agent creating the room to attach it, or afterward, on the room’s page in the Gateway, select Attach package.
For example, to attach a reference, ask:

​
Add materials to rooms that already exist

To distribute materials to existing rooms, add them to a package the rooms share, so every room gets them in one step. If they don’t share a package yet, first make one and attach it to each room that will share the materials.