Cette page n’est pas encore traduite.

Bring in your company's people

This page is for an organization's owners and admins. You will bring in the people from your company's directory, so writers can name the right person in an instruction, such as the approver of a refund.

Why bring in your people

An instruction often names a person: "Ask the finance lead before you refund more than €500." When a writer types @, the editor offers people by name, with their picture and job title. The instruction then points to that exact person, not only to their name.

In Preview, a person shows who they are. Someone who no longer works at your company is marked, so you notice when an instruction names someone who left. See Mention people, tools and other instructions.

Your organization's own members are always there. A directory adds the rest of your company, including people who never sign in to instruction.md.

Before you start

Plans On Pro, Team, and Enterprise

  • Your role. Only the organization's owners and admins add, pull again, hide and remove directories. Other members see the list, and the line Owners and admins add directories. See Invite people and choose their roles.
  • Your plan. Your own members are there on every plan. If your plan doesn't include directories, Add a directory shows Pro and above with See plans.
  • A sign-in for the directory. Ask your IT team for the address and a read-only sign-in, as the list below says for each kind.

Where your people come from

Open Integrations ▸ Directories in the editor's side bar. The page has three parts.

  • This organization: your members, and the people your company's sign-in system adds for you (see Automatic updates with SCIM). The row Members and provisioned people says how many.
  • Added directories: the directories you added, each with how many people it has, how many are no longer there, and who pulled it and when.
  • Add a directory: where you add one.

Add a directory

  1. Open Integrations ▸ Directories

    Go to Add a directory.

  2. Choose where your people are

    In Where your people are, choose one of these. Each asks only for what it needs.

    • Okta: Your Okta address, such as acme.okta.com, and an API token. A read-only token is enough.
    • Microsoft Entra ID: Your tenant, which is its id or its domain such as contoso.onmicrosoft.com. Then the Client id and Client secret of an app your IT team made, which may read your users. Or paste an access token in Or an access token instead, and leave the tenant empty.
    • Google Workspace: an access token that may read your users. Under Only one domain?, type a domain, or leave it empty for all of your account's users.
    • Workday: The report's address, a Workday report of your people, and its Integration user and Password.
    • A SCIM server: Its SCIM address, and a token if it asks for one.
    • Another address (JSON): Its address, any address that answers a list of people, and a token if it asks for one.
    • A file (CSV or JSON): a spreadsheet saved as CSV with a header row, or a JSON list. At most 5 MB.
  3. Match the fields (lists and files only)

    For Another address (JSON) and A file (CSV or JSON), open Where each field is under Field names. Fill it in only if your list names its fields differently from id, name, email, title, department, manager and picture. For example, if your spreadsheet's column is "Role" instead of "title", type Role in Job title.

    The fields are Where the list is, Id, Name, Email, Job title, Team, Manager, Picture and Still here.

  4. Add it

    Press Add. For a file, press Upload file… and choose it. The button shows Pulling… while it reads. Then you see Added its name: 240 people, or similar.

Adding a directory, with its field names matched.

What is kept, and what is never kept

  • Your sign-in is used once. The token, secret or password is used for this one pull, then forgotten. instruction.md never keeps it. Each Pull again asks for it again.
  • Only names and job details are kept. For each person: their name, work email, job title, team, manager, picture and office or city, and whether they still work there. Some directories add a few more job details, such as an employee number.
  • Only your members see them. People are shown to your organization's members as they write. Nothing about a person is ever public.
  • Up to 20,000 people a directory. A directory counts as one of your organization's 100 integrations.

Pull again

A directory doesn't update by itself. To bring in new people and changes, press Pull again on its row.

  1. Press Pull again

    If the directory needs a sign-in, a row opens under it, Its sign-in: "To pull it again: used for this one pull, never kept". For a file, you choose the file again instead. A directory that needs no sign-in is pulled at once.

  2. If asked, give the sign-in and press Pull

    You see Pulled its name again: 245 people.

People who left

When a pull no longer finds someone, or finds them marked as inactive, they are kept and marked as gone. The row says how many, such as 3 no longer there. An instruction that names them still shows their name. In the editor and in Preview, they are marked as having left. If a later pull finds them again, they count as here again.

Hide or show a directory

Each directory has a switch, Offer its name's people as you write. Turn it off to stop offering its people when writers type @. Its badge says Hidden. People already named in instructions still show who they are. Your own members have the same switch, Offered as you write, on the Members and provisioned people row.

Automatic updates with SCIM

Plans On Team and Enterprise

SCIM is a common way for a company's sign-in system, such as Okta or Entra ID, to keep other services' lists of people up to date. With it, your sign-in system adds, changes and removes your people in instruction.md by itself.

It differs from a directory in two ways:

  • It is automatic. Your sign-in system sends each change as it happens. A directory changes only when you press Pull again.
  • It makes people members. A person SCIM adds can be named at once. When they first sign in with their work email, the editor shows them an invitation to your organization, which they accept or ignore. A person SCIM removes loses their membership. A directory only lets writers name people. It never makes anyone a member.

Joining takes a free seat. See Plans, limits and billing.

  1. Find Automatic updates (SCIM)

    It is under This organization, on Integrations ▸ Directories. Only owners and admins see it.

  2. Press Make a token

    Only an owner can make one. Admins see Owners.

  3. Copy the token and the address

    You see Your SCIM token, "Shown this once — paste it into your identity provider now", and the SCIM address. Copy both into your sign-in system, where it asks for a "base URL" or "tenant URL" and a token. Then press I've kept it.

Once it works, the row says Your identity provider updates this organization's people, with when it last did. Each token's row says who made it, and when it was last used.

  • Rotate makes a new token. The old one stops working at once, so paste the new one into your sign-in system right away. Only owners can rotate.
  • Revoke stops a token. The editor asks Revoke this SCIM token? "Your identity provider's next update with it is refused. People already here stay."
  • An organization has at most 5 working SCIM tokens.

How to set up each sign-in system is on the developer page: SCIM and people directories.

Check it worked

  • The directory's row shows how many people it has and Offered.
  • In an instruction, type @ and start typing a name from the directory. The person is offered, with their picture and job title.

Remove a directory

Press Remove on its row and confirm. Its people go too. Instructions keep the names they wrote, and those people show as unknown. If you add a directory of the same kind again later, the people named before are found again.

If it doesn't work

What you see What to do
Its API token first, or another "… first" A field is missing. Fill in what it names, then press Add again.
The directory asks for its sign-in The address needs a token or password. Type it in the sign-in field, then try again.
The file is larger than 5 MB Split the list into smaller files, or leave out columns you don't need.
Didn't pull, on the row Read the line under it, which says why. Check the sign-in with your IT team, then press Pull again.
No one shows when you type @ Check that the directory says Offered, not Hidden.
Making the token didn't work Only an owner makes SCIM tokens, and at most 5 can work at once. Revoke one first.

For anything else, see Something isn't working.

Questions

How do I connect Okta or Entra ID: a people directory or SCIM?

Use a directory to let writers name your people. Use SCIM to have Okta or Entra ID add and remove your members by themselves. You can use both. Each needs a plan that includes it: see Before you start and Automatic updates with SCIM.

Does instruction.md keep our directory's password or token?

No. It is used for one pull and then forgotten. Each Pull again asks for it again.

What do you keep about each person?

Their name, work email, job title, team, manager, picture, office or city, and whether they still work there, and from some directories a few more job details. Only your organization's members see them.

What happens when someone leaves?

The next pull marks them as gone. Instructions that name them still show the name, marked as having left, so you can update the instruction.

Last checked against the product:

Was this page helpful? Report a problem