V. Commands

These are commands that must be actively called by a user to take effect. Along with the command call itself (i.e. !command), they often require, or optionally allow, several other parameters to be given. Parameters are positional by Discord's restrictions, meaning the orders and amount will always matter.

Always remember...

1. Everything is cASe-SenSiTIve.
2. Position matters.
3. Channel matters.
4. Your roles matter.
5. Good Practice: Put all your parameters inside quotes like "this".

---

V.a. Interview Commands

These commands help Guest users to give their information and get a general idea of the org when Orientation members are not available.

---

!interview

@bot.command(name='interview', 
             brief=" = Begins an interview with whichever "Guest" calls it.",
             description="Begins an interview with whoever calls it. After completion and submission of the interview, it will create an entry in the long-term JSON file.")
@commands.has_role('Guest')
@commands.cooldown(1, 1800, commands.BucketType.user)
async def dm(ctx):

This function has no parameters, and can only be called on its own with no modifiers. It has a few requirements:

1. must have "Guest" role
2. must be in specified channel #request-orientation

It starts a DM with the user who called it, then works in tandem with the event handler, on_raw_reaction_add, to identify the user's choices and submit them into the designated orientation logging channel. Simultaneously, upon submission by the user, it will add them into the long-term JSON file logs. After that it will simply wait for approval or denial of the log before moving on, making changes to the user's roles and nickname, and finalizing their admission/denial to/from the org.

Example: !interview

---

!botblob

@bot.command(name="botblob",
             brief="Send an embed in recruit channel explaining ICARUS.",
             description="Sends an embed message into the designated recruit/orientation request channel that explains the idea of the bt and using it for an intro orientation.\n\nPlease note: you must still ping and communicate with the new user in some way, this just saves some typing and looks nice."
             )
@commands.has_role(ORIENTATION_ROLE_NAME)
async def botblob(ctx):

This function will simply send out a neat and tidy embed that includes details on the bot an how to use it for new recruits in #request-orientation chat. You will have to preface it with something so the user is notified by ping. Respond to the user's request with something along the lines of: "Hey, @user! Unfortunately, we are indisposed, but if you go through the basics with our bot, ICARUS, he'll get some basic info from you and give you an idea of what the org is about. Let me know if you have any questions." Basically, make sure to keep some human element and interaction with the new recruit.

This function has no parameters, and can only be called on its own with no modifiers. It has a few requirements:

1. must have "Orientation" role
2. must be in specified channel #recruit-logging

Example: !botblob

---

V.b. Logging Commands

These commands help orientation members manipulate and cite the long term longs. These long term logs have the benefit of persistence, allowing us to keep an archive of every user, interview, and bad apple we may come across. It also allows us an easy way to keep track of immutable descriptors, such as a user's Discord ID number.

---

!create

@bot.command(name='create', 
             brief=" = Manually creates a log entry for a given user and log message.",
             description="Manually creates a log entry for a given user and log message. REQUIRES A MINIMUM OF MESSAGE_ID AND USER_ID. All other parameters are optional but must be given in order if you desire to use them. Otherwise use the command !update after creating the log.\n\nmessage_id = (INTEGER) The ID of the message in Orientation Log Channel for the user's interview.\nuser_id = (INTEGER) The Discord User ID of the member.\ndiscord_username = (STRING) The Discord username of the member.\nrsi_username = (STRING) The RSI username of the member.\nnotes = (STRING) Anything you may want noted within the log.\nadmitted = (BOOLEAN) Whether or not the user has been admitted. True=admitted, False=denied, Null=pending.\nred_flag = (BOOLEAN) Will notify Command if a user joins that can be found in logs with this flag. True=notify, False=default.\nred_flag_msg = (STRING) Whatever message you may want displayed when a flagged user joins.")
@commands.has_role(ORIENTATION_ROLE_NAME)
async def create(ctx, message_id:int, user_id:int, discord_username="", rsi_username="", notes="", admitted:bool=None, red_flag:bool=False, red_flag_msg=""):

!create will do as you expect and create an entry in the long term logs. It takes a minimum of two parameters, in this order:

1. the message ID of the user's interview in #recruit-logging
2. the Discord ID of the user who is being logged

Permissions required:

1. must have "Orientation" role
2. must be in specified channel #recruit-logging

It does have several optional parameters though, if you would like to fully fill out the log on the first call of the command. The other option would be to use !update after the initial log has been made. The full parameter list is as follows:

1. REQ the message ID of the user's interview in #recruit-logging
2. REQ the Discord ID of the user who is being logged
3. OPT the user's discord username
4. OPT RSI username
5. OPT notes you want applied to the user
6. OPT admitted (boolean). meaning the only two options are True or False
7. OPT red flag (boolean). meaning the only two options are True or False
8. OPT the red flag message if you wished to set red_flag to True

Example: !create 123456789123456789 123456789123456789

---

!update

@bot.command(name="update",
             brief=" = Will update a log, given an ID and the item you want updated.",
             description="Update a log, given an ID and the item you want updated. The key and value pair provided will be what is updated, and what it is updated to.\n\nFor reference, 'KEY':'VALUE' is how it appears in the logs while using the !find command.")
@commands.has_role(ORIENTATION_ROLE_NAME)
async def update(ctx, search_ID, key, value):

!update lets an Orientation member change particular key-value pairs of a long term log. A "key" is like the title of the info, and the "value" is the actual information. Keys are immutable to users, whereas values will be updated. The parameters are as follows:

1. search_ID = either the message ID of the log, the user's Discord ID, the user's RSI username, or the user's Discord username. They are preferable in that order, and will algorithmically search in that order.
2. key = the key you would like to change the value of
3. value = the value you would like it changed to

Permissions required:

1. must have "Orientation" role
2. must be in specified channel #recruit-logging

Allowed keys and their corresponding values:

"Discord User": `any string and/or integer`, 
"Discord ID": `any integer`, 
"RSI User": `any string and/or integer`, 
"Notes": `any string and/or integer`, 
"Admitted": `True` or `False`, 
"Red Flag": `True` or `False`,
"Red Flag Message": `any string and/or integer`

Please make sure that Booleans are case-sensitive. There are checks in place to help you utilize these, however, good practice is to not need those checks and safeties. It is also good practice to put your parameters in "quotations", but it is required when using spaces in your parameters. Keys are also case, spelling, and spacing sensitive. If you want to change the RSI username, you must specify the key exactly as it appears in the examples above. i.e. "Discord User" would be what you type as the parameter for "key".

Example: !update 123456789123456789 "Notes" "This is an example parameter. I can use any UTF character inside these quotes."

---

!find

@bot.command(name='find', 
             brief=" = Find a log by giving it an ID or name.",
             description="Will find a log by giving it log's message ID, the user's discord ID, an RSI username, or a Discord username. It will search numerical queries through messageID and discordID first. It is recommended to not rely on using the Discord username, as it can easily be changed.")
@commands.has_role(ORIENTATION_ROLE_NAME)
async def find(ctx, query):

!find will find and then display the log you search for. It has one parameter, which is the search query itself. It accepts the log ID (message ID of the log in #recruit-logging), the user's Discord ID, the user's RSI username, or the user's Discord username. The search query is preferred in that order. Immutable search queries such as the Discord ID's are always preferable over things that can, and are, often changed, such as usernames.

Parameter:

1. search query = log ID, Discord ID, RSI username, or Discord username

Permissions required:

1. must have "Orientation" role
2. must be in specified channel #recruit-logging

Example: !find "Turtle-12"

---

!kill

This will kill all the Bot's internal processes and shut down all functions. This is a hard kill meaning that any ongoing sessions with users, unsaved data, and current statuses will be wiped immediately. ICARUS will need to rebooted from the server side if this command is used. There are no channel restrictions, however, please be aware that the roles of the bot must allow access to the channel for ICARUS to be able to see that the command has been used. If the kill command is used in an Officers' chat, it will not work.

Permissions required:

1. must have "Fleet Command" role

Example: !kill

---