Overview

While it's possible to use Sobol without installing Sobol Bot, 99% of the time you'll want to install Sobol Bot for your Discord.

With Sobol Bot installed, you can do things like:

• Sync users between your Discord and your Sobol instance*
• Give Sobol permissions to specific Discord roles
• Map Discord roles to specific Teams in Sobol
• Set update reminders to ping specific Team stakeholders in Discord

Installing Sobol Bot is easy. You simply install it like you would any other Discord bot, and then you set Sobol permissions to Discord roles. Next, you run a slash command to sync between Discord and your Sobol instance.

Once you've done that, your members can start inviting themselves to Sobol and filling out their member profiles!

Regular-level members will be able to contribute to Workspaces in Sobol. Admin-level members will be able to add people to Teams and map accountabilities!

 

Requirements

In order to setup bot provisioning between Sobol and Discord, the following are required:

  • You need a Sobol account and have Admin permissions for a Sobol Organization.
  • You must already be a Discord User and EITHER hold server ownership or have a role with the “Manage Server” permission enabled.

If for any reason you do not have the following, please contact support@sobol.io.

 

Set Up Sobol in Three Steps

To install Sobol Bot in your Discord Server, complete the following:

Step One: Install the Bot

First, you need to install the Sobol Bot into your Discord. 

In Sobol

  1. Login into your organization on Sobol (make sure you are an admin).
  2. Once logged in, find Settings on the main left hand side menu.
  3. Expand Organization Settings and click on Applications.
  4. Once in Applications, click on the Add Application button (top right corner).
  5. Once the modal opens, click on the Discord app from the selection.
  6. Once the app has been installed, a configuration drawer will open.
  7. In the configuration drawer, copy the API Key and then click on Install Sobol Bot.
    1. A browser window will open and will require you to:
      1. Select the server you wish to install the bot on.
      2. Authorize the Sobol Bot with the prescribed Discord permissions set.
    2. And voila! Sobol Bot should ping you from Discord Server.
In Discord

In your Discord Server, add your Sobol API Key to Sobol Bot so that it can establish a connection with your Sobol Organization. Enter the following command:

/set-api-key <SOBOL_API_KEY> - paste the key you generated and copied in the previous step.

 

Step Two: Map Discord Roles to Sobol Permissions

This feature allows you to map a Discord Role to a Sobol User Permission. Use the following commands to map the roles to those permissions:

1. Read Only: Member can only view and navigate map /user-map add-readonly <DISCORD_ROLE>

2. Regular: Member can edit Sobol member profile and contribute to workstreams /user-map add-regular <DISCORD_ROLE>

3. Admin: User can add/edit/delete member profiles and Teams. Full add/edit/delete access to Sobol instance. Admin should only be granted to a small handful of trusted members of your Discord. /user-map add-admin <DISCORD_ROLE>

For example: /user-map add-readonly @everyone

You can map multiple Discord Roles to a given Sobol User Permission by running these commands multiple times. When you are finished, you can review the mapping by running:

/user-map list

You can also remove any role from the mapping by running:

/user-map remove <DISCORD_ROLE>

Important: Don’t forget to add an admin role that you have or your Sobol user will be archived or demoted.

How are these roles used?: In BanklessDAO, For instance, Level 1 users in Bankless DAO are given "Regular"-level permissions in Sobol. "Admin"-level permissions are given to "Sobol Editor", "Cartographer", and server admins.

"Read-only" perms are given to "Guest Pass" members in Bankless DAO.

Note: Anyone with a Discord Role corresponding to a Sobol User Permission will be automatically added to Sobol with the highest permission level available to them. If someone loses all Discord Roles with permissions or leaves the Discord Server, their Sobol User will be archived and they will lose access to the Sobol Organization.

 

Step 3: Map Discord Roles to Sobol Teams [Optional] or Roles [Optional]

Map Discord Roles to Sobol Teams

This feature allows you to map a Discord Role to a Sobol team and automatically add all holders of the role as members of the team in Sobol. Use the following commands to map the roles to teams:

/team-map add <DISCORD_ROLE> <SOBOL_TEAM_NAME (search)>

To re-assign the role to a different team, re-run the command with a different team name

To unassign a role from the currently assigned team:

/team-map remove <DISCORD_ROLE>

When you are finished, you can review the mapping by running:

/team-map list

 

Map Discord Roles Roles to Sobol Roles

This feature allows you to map a Discord role to a Sobol role and automatically add all holders of the Discord role as assignees of the role in Sobol. Use the following commands to map Discord roles to Sobol roles: 

/role-map add <DISCORD_ROLE> <SOBOL_ROLE_NAME (search)>

To re-assign the role to a different team, re-run the command with a different team name

To unassign a role from the currently assigned team:

/role-map remove <DISCORD_ROLE>

When you are finished, you can review the mapping by running:

/role-map list

 

Link Existing Sobol Users

In the event that you have existing users in Sobol (including yourself) that correspond with a user in your Discord Server, use the “link” command to avoid duplicate users provisioned into Sobol:

In Discord:

Enter the following command and the Sobol user will be linked to the specified Discord user:

/link create <DISCORD_USER> <SOBOL_USER_NAME (search)>

Note: You can also do this after starting synchronization but note that the newly provisioned Discord User will be deleted in favor of the existing one in Sobol. The bot will warn you before it deletes a Sobol user.

Made a mistake?

Enter the following command and the Sobol user will be unlinked:

/link remove <SOBOL_USER_NAME (search)>

Tip: Always try to unlink a Sobol user from a Discord user with /link remove instead of overwriting a link with /link create to avoid accidentally deleting a Sobol user.

 

Start Provisioning

When you are ready to being provisioning, run the following:

/sync start

The bot will then start synchronizing all Discord Users with roles that are mapped to Sobol User Permissions. You can update the mapping at any time and it will update all Sobol Users accordingly.

You can pause synchronization at anytime using the following command:

/sync stop

Tip: If your Discord server has a lot of users (hundreds and thousands), use /sync stop to pause synchronization when you are editing mappings using the /user-map , /role-map or /team-map commands to avoid lag. Remember to re-enable synchronization with /sync start after you're done.

You can force a full resynchronization in the event of mismatches using the following command:

/sync force

You can also force an individual resynchronize in the event of a single mismatch using the following command:

/sync user <DISCORD_USER>

 

Scheduled Updates

Create real-time messaging into your discord to prompt your members to give updates!

/update create <FREQUENCY> <TEAM NAME> <TITLE> (<AT_MENTION>) (<CHANNEL>)

This creates a scheduled update that will post a message at the specified frequency to prompt users to post their updates against the specified team.

The optional at_mention can be a @user or @role that will be mentioned in the update reminder message so they can be notified.

The optional channel allows you to specify the channel in which the update message will be posted, if it is excluded then it defaults to the channel in which you executed the update create slash command.

The frequency is defined using cron syntax, `minute` `hour` `day of the month (1-31)` `month (1-12)` `day of the week (0-6, Sun = 0, Sat = 6)

* is a wildcard that can take any possible value.

For more details, see https://en.wikipedia.org/wiki/Cron

 

Examples:

The first day of each month at 12:00 UTC: `0 12 1 * *`

Every day at 12:00 EDT: `0 16 * * *`

Every Tuesday at 14:30 UTC: `30 14 * * 1`

Every weekday at 16:00 EDT: `0 20 * * 1-5`

/update list

This will DM you a list of each scheduled update. You can then click edit on any one you wish to make changes. After clicking the edit button, buttons will appear that will allow you to pause/resume the update, edit the frequency, and delete the update. 

 

Troubleshooting Tips

  • Provisioning Errors: if any errors occur while provisioning, they will be logged in the private #sobol-bot-log channel.
  • Invite Links: all users provisioned to Sobol will have their invite link DM’d to them directly in Discord. You will be notified on #sobol-bot-log if a user has disabled DM’s on your server.
  • User Changes In Sobol: Discord will overwrite user permission and name changes in Sobol upon the next resynchronization.
  • Default Permissions: when adding permissions, you can use @everyone to give every user a certain permission level by default.

 

Command Reference

Please visit our Command Reference for more information on Sobol Bot slash commands.

 

Support

We are here to help! If for whatever reason you are not successful with these instructions, please reach out to support@sobol.io. Feedback is always appreciated!