Roles of your organization's own

For an organization's Owners and Administrators.

What it is for

ContactRoll's nine ready-made roles are the same in every organization (see Roles). When none of them fits a job in your organization — a team lead who works the queue and runs call groups but touches no billing, say — an organization on the Plus plan can make roles of its own. Each one starts as a copy of a role you already have, gets its own name and a sentence saying what it is for, and is then changed permission by permission and, for each kind of record, reach by reach.

A role of your own works everywhere a ready-made role does: you give it to members on /team, name it in an invitation, narrow it under "What each role sees", and every page and every refusal follows it. Where ContactRoll names who may do something, it names your roles too, as "someone with the role" and the role's name — for example "Only an Owner, an Administrator or someone with the role Team lead may give members their roles."

The plan

Every organization is on a plan, and roles of an organization's own come with Plus.

• The plan is chosen on the Billing page, by whoever may manage billing, and ContactRoll keeps a record of each change. The Roles page, /settings/roles, says which plan you are on just under its opening paragraph: "This organization is on the Plus plan: it may make roles of its own, each from a copy of a ready-made one or of one of its own." On any other plan it names that plan: "This organization is on the {plan} plan. Roles of an organization’s own come with the Plus plan."
• On any plan but Plus, nobody makes a role, changes one or gives one to a member or an invitation. Asked anyway, ContactRoll says "Roles of an organization's own come with the Plus plan; this organization is on {plan}." — and, refusing a change to a role, a role given, or a narrowing, adds "The roles it made keep working as they are."
• An organization that leaves Plus keeps the roles it made, working. Their members may do exactly what they did, and the plan line says so: "…the one it made keeps working as it is, and none is made, changed or given until it is on Plus again." (or, for several, "…the 3 it made keep working as they are…"). In that time you can still delete one of your roles, move its members to a ready-made role, remove a member who holds one, and see what each one may do; an invitation already sent with one of your roles can still be accepted. You cannot make, change or give one until the organization is on Plus again.

What a role of your own holds

• Permissions. Any of the permissions listed on the Roles page, with two exceptions that belong to the Owner role alone: closing the account (and reopening it), and transferring ownership. A role of your own never holds those two, so it is never an Owner, and only an Owner role can do what only an Owner does.
• Three permissions narrowed as the Supervisor holds them. Downloading call recordings and deleting them may each be held for every call or only "for the calls that rang a call group they are in", and refunding without asking (approving what others asked for) for any amount or only "up to the product’s cap for agents". No other permission can be narrowed.
• The ten ways of seeing, always. "See contacts and callers", "See companies", "See cases and the queue", "See deals and the pipeline", "See tasks", "See notes and comments on the records they can see", "See the calls on the record", "See campaigns, their pieces, sequences and forms, and how they did", "See flows and what they did, and test one on recent events" and "See the dashboard, the measures and the reports" are every role's, and yours too. Nothing turns them off. Which records of each kind a role sees is decided by its reach, and a reach of None keeps a kind of record from it (below).
• A reach for each kind of record — contacts, companies, cases, deals, tasks, notes and calls — and each act — see, change and remove: "Everything", "My team’s", "Mine" or "None", with or without "and unassigned". These are the same four reaches, with the same meaning, described in Who sees what. A role of your own can be narrowed even when it was copied from the Owner or Administrator role, which are never narrowed themselves.

The one rule: nothing beyond your own role

Nobody makes, changes, deletes, gives or views as a role that holds more than their own role does: a permission theirs does not hold (or holds only narrowed), or a reach wider than theirs. "Wider" counts records nobody owns separately: "Mine" with "and unassigned" is not within "My team’s" without it. A change is judged against your role as it stood before the change, so nobody widens the role they hold themselves.

The pages offer only what this rule allows, and ContactRoll refuses the rest in words, for example "Nobody makes a role beyond their own: it may refund without asking, and issue or decline what others asked for, which your role may not." or, saving the editor with more than your role holds, "Nobody gives a role more than their own: …" naming what (a role that already reaches beyond yours is refused "Nobody changes a role beyond their own: …").

Setting it up

Making, changing and deleting roles, and viewing as a role, are for members whose role may "give members their roles": the Owner, Administrators, and any role of your own given that permission.

1. Open the Roles page. Go to /settings/roles (on /team, the link "What each role may do"). Read the plan line under the opening paragraph.
2. Start a new role (Plus only). Press "New role". Under "New role" the page says: "It starts as a copy — what the role it is copied from may do, and what it reaches here — and is changed from there. A copy of the Owner leaves out what only an Owner may do: closing the account and transferring ownership."
   • In "Copy of", choose the role to start from. The list holds the ready-made roles and your organization's own that your role holds all of; it starts on your own role. An Owner may copy the Owner role: the copy gets everything the Owner holds except the Owner's two.
   • In "Name", type its name: 1 to 40 characters. It cannot be the name or key of a ready-made role, whatever the capitals, nor the name of another of your roles in use.
   • In "What it is for", say in a sentence what the role is for: 4 to 400 characters. This is the sentence the Roles page, the member page and the role editor show beside the name.
   • Press "Make the role". The page says "{name} is made: change what it may do below." and opens the editor on the new role.
3. Change what it may do (Plus only). Under "The roles", each of your roles is marked "This organization’s own role, first copied from" and the role it was copied from. Press "Change {name}" to open the editor.
   • "Name" and "What it is for" can be changed here too.
   • Under "What it may do" the page says: "Seeing is always on, for every role: what a role sees of each kind of record is decided by its reach, below." The permissions follow under the Roles page's eleven headings. The ten ways of seeing are drawn with a mark and no box, followed by "always on" — and, for the seven kinds of record, "its reach, below, decides which". Every other permission has a box: tick it to give it, untick it to take it away. A box is never offered where the permission is the Owner's alone ("Only the Owner role"); one your role does not hold ("Your role does not hold this") cannot be ticked, though a copy that already holds it shows it ticked, and it can be unticked. For the three permissions that can be narrowed, a choice beside a ticked box says how far: "Every one" or the narrowed form. "Every one" is offered only if your own role holds the whole permission.
   • Under "What it reaches" the page says: "Of each kind of record: whose it sees, changes and removes. A member always sees and changes their own." Each kind of record — Contacts, Companies, Cases, Deals, Tasks, Notes, Calls — has a choice for "See", "Change" and "Remove": "Everything", "My team’s", "Mine" or "None". A reach wider than your own role's for that kind and act is shown but cannot be picked. Beside a narrowed reach is the box "and unassigned"; it starts ticked when you narrow from Everything.
   • As you tick and choose, the page says in two lists what the role "may" and "may not" do, area by area, with each narrowed reach in brackets. It also warns of combinations that make little sense — the role may remove a kind of record it may not change, removes with a reach of None, may download, delete or see who listened to recordings it may not listen to, acts on billing it may not see, approves refunds it may not ask for, or sends marketing it may not approve. These warnings do not stop a save.
   • Change is never wider than See, and Remove never wider than Change. If a choice breaks that, the page says which kind — "Who they may change cannot be wider than who they see: widen what they see first (contacts)." — and "Save" waits until it is fixed. Unlike "What each role sees", the editor does not narrow Change and Remove for you.
   • Press "Save {name}", or "Cancel" to leave it as it was. The whole role is saved at once. The page says "{name} is saved: it takes effect on each holder’s next page." From then on ContactRoll asks every request of the role as it now stands; a holder's screens show it the next time they move to another page or come back to the tab.
4. Give it to members. On /team, choose it in a member's "Role", or in "Role" when you invite somebody, exactly as for a ready-made role (see Roles). It is offered only on Plus, and only if your role holds all of it. A member who holds a role of yours keeps it in their "Role" choice whatever the plan, until somebody gives them another. The invitation email says the role by its name: "with the role {name}".
5. Narrow it one setting at a time, if you prefer. On Plus your roles are also in "Role" under "What each role sees" on the same page, and are narrowed there as Who sees what describes. On any other plan they are not listed there at all.
6. Delete a role you no longer need. Press "Delete {name}". This works on every plan. The page asks who holds it ("Asking who holds it…"), then:
   • If nobody holds it, it says "Nobody holds {name}." and offers "Delete {name}".
   • If members hold it, it lists them ("2 members hold {name}:") and asks where to put them under "Move them all to" (or "Move them to", for one member), offering the roles you may give. "Move and delete {name}" gives each of them that role, by the same rules as changing a member's role on /team, and then deletes the role. The page then says, for example, "2 members moved to Agent, and Team lead deleted."
   • If an invitation not yet accepted names the role, the page says so — "An invitation not yet accepted names {name}: revoke it on Team first." — and the delete waits until you have revoked it on /team.
   • As the page says, "A deleted role is kept for the record of who held it, and given to nobody again." Its name is free for a new role. The nine ready-made roles cannot be deleted or changed.
7. Check the record. Under "Every make, change and delete" the Roles page lists, newest first, who made each of your roles and from which ("ana@example.com made Team lead from Supervisor"), who changed one ("changed Team lead (was Lead)", ", and what it is for" when its sentence changed), and who deleted one. Each change lists what the role gained ("Added: …"), lost ("Taken away: …") and every reach that moved ("Sees only their own cases — was every one of the organization’s cases"). A member who has since left is shown as "Somebody". Until a role is made it says "No role of this organization’s own has been made yet." The page shows the latest 200; nobody can change or delete the record, and it is in the organization's export.

Viewing as a role

"View as {name}" on the Roles page shows what a member holding that role is shown, without giving the role to anybody. It is drawn under every role your role holds all of — the ready-made roles as well as your own, on every plan — and opens /settings/roles/{role}/view.

The page is headed "Viewing as {name}" and says: "Read-only: nothing here changes anything, and each company shown below is recorded as viewed as {name}. It shows what someone with {name} sees." Below that:

• "The navigation": the sections of the shell and "Mentions" (the same for every role, as the shell draws them), and the Settings pages the role is shown — always "Yours", "Flows" and "Business hours", and "Calling" (while calling is on in your organization), "Integrations", "API keys" or "Webhooks" where the role may change something on them. A line says whether it places calls and takes the calls that come in, and "no Calling settings" where it has none.
• "A company page": choose a company under "Company" (the first 50 of the companies you see, by name). ContactRoll asks, for that company, whether the role reaches it, may change it and may remove it — by the role's permissions and its reach — and says so: "Someone with Team lead sees Crumbhollow Bakery, may change it and may not remove it." or "Someone with Team lead does not see Crumbhollow Bakery." A line under it says what the role sees of companies, contacts, cases and deals. Then the company's own page, drawn with the role's permissions: the panels and buttons on it are the ones the role gets. Nothing in it can be pressed, typed into or focused. Where the role does not see the company, the frame shows what such a member would read instead.
• The lists on the page are yours, not the role's. As the page says above the frame: "The people, cases and deals listed on this page are the ones you see — yours, not {name}’s." To learn what the role reaches of those, read the line above it, or the role's reach under "What each role sees".

Each company asked about is recorded: who viewed, as which role, which company, and what the role was answered. Under "Who viewed the organization as a role" the Roles page lists the latest 100, newest first — for example "ana@example.com viewed Crumbhollow Bakery as Team lead: it sees it, changes it" — naming the company only where you can see it yourself ("a company" otherwise). Until anybody has viewed, it says "Nobody has viewed the organization as a role yet." The record is in the organization's export and nobody can change it.

What a member sees

• The Roles page. Every member can open /settings/roles and sees every role in use, your organization's own included, each with its sentence, how many members hold it, and — on a press of its name — what it may do, area by area, and under "What it reaches here" any reach that is narrowed. The plan line is shown to everybody. "New role", "Change", "Delete", "View as", "Every make, change and delete" and "Who viewed the organization as a role" are drawn only for members whose role may give members their roles.
• A member's page. On /team, every member's address opens their own page, /team/{member}. It shows their "Role" — and for one of your roles "this organization’s own role, first copied from" the role it came from — "What it is for", and the date they joined. "What may {member} do?" (or "What may you do?" on your own) opens exactly what the role lets them do and, where it is narrowed, what it reaches; "Every role" leads back to the Roles page. Every member can open every member's page.
• The top bar. On a wide screen, a member holding one of your roles sees its name beside their address, where a ready-made role shows its short key.
• Everywhere else, a member holding one of your roles is offered what its permissions allow and reaches what its reach allows, exactly as with a ready-made role. Refusals that name who may include your roles by name.

Where your roles appear outside the Roles page

• The organization's export. "Download everything" on /team carries your organization's roles, deleted ones included, with what each holds; the record of every make, change and delete; the record of views as a role; and the record of the organization's plan.
• Webhooks. An outgoing webhook can hear "A member’s role changes" (member.role_changed), set up at /settings/webhooks. Each delivery names the member (id, email, joined_at), the role they hold now (role, its key; role_label, its name; role_custom, whether it is one of your organization's own) and the one they held (from_role, from_role_label, from_role_custom). A role of your own has a key of the form custom_ and sixteen letters and digits, which does not change when you rename it.
• The API. GET /members lists every member, by address, with the same fields as above. It answers only a key whose maker may give members their roles, asked at every request; otherwise it answers 403: "The member who made this key may not give members their roles now, so the key may not read them either." It takes no other method and has nothing under it.
• Invitations. An invitation can name one of your roles, on Plus, and its email says the role by its name.