Mathis/allianceauth
1
0
Fork 0
mirror of https://gitlab.com/allianceauth/allianceauth.git synced 2025-12-18 23:05:07 +01:00
Code Issues Packages Projects Releases Wiki Activity

Documentation overhaul

Browse Source
This commit is contained in:
Erik Kalkoken
2020-03-05 02:23:58 +00:00
committed by Ariel Rin
parent 9c880eae8a
commit 8137f1023a
84 changed files with 844 additions and 530 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
docs/features/apps/autogroups.md Normal file
View File

@@ -0,0 +1,35 @@
# Auto Groups
```eval_rst
.. note::
New in 2.0
```
Auto groups allows you to automatically place users of certain states into Corp or Alliance based groups. These groups are created when the first user is added to them and removed when the configuration is deleted.
## Installation
This is an optional app that needs to be installed.
To install this app add `'allianceauth.eveonline.autogroups',` to your `INSTALLED_APPS` list and run migrations. All other settings are controlled via the admin panel under the `Eve_Autogroups` section.
## Configuring a group
When you create an autogroup config you will be given the following options:
![Create Autogroup page](/_static/images/features/apps/autogroups/group-creation.png)
```eval_rst
.. warning::
After creating a group you wont be able to change the Corp and Alliance group prefixes, name source and the replace spaces settings. Make sure you configure these the way you want before creating the config. If you need to change these you will have to create a new autogroup config.
```
- States selects which states will be added to automatic Corp/Alliance groups
- Corp/Alliance groups checkbox toggles Corp/Alliance autogroups on or off for this config.
- Corp/Alliance group prefix sets the prefix for the group name, e.g. if your Corp was called `MyCorp` and your prefix was `Corp`, your autogroup name would be created as `Corp MyCorp`. This field accepts leading/trailing spaces.
- Corp/Alliance name source sets the source of the Corp/Alliance name used in creating the group name. Currently the options are Full name and Ticker.
- Replace spaces allows you to replace spaces in the autogroup name with the value in the Replace spaces with field. This can be blank.

158
docs/features/apps/corpstats.md Normal file
View File

@@ -0,0 +1,158 @@
# Corporation Stats
This module is used to check the registration status of Corp members and to determine character relationships, being mains or alts.
![corpstats](https://i.imgur.com/9lZhf5g.png)
## Installation
Corp Stats requires access to the `esi-corporations.read_corporation_membership.v1` SSO scope. Update your application on the [EVE Developers site](https://developers.eveonline.com) to ensure it is available.
Add `'allianceauth.corputils',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.
## Creating a Corp Stats
Upon initial install, nothing will be visible. For every Corp, a model will have to be created before data can be viewed.
![nothing is visible](/_static/images/features/apps/corpstats/blank_header.png)
If you are a superuser, the add button will be immediate visible to you. If not, your user account requires the `add_corpstats` permission.
Corp Stats requires an EVE SSO token to access data from the EVE Swagger Interface. Upon pressing the Add button, you will be prompted to authenticated. Please select the character who is in the Corporation you want data for.
![authorize from the EVE site](/_static/images/features/apps/corpstats/eve_sso_authorization.png)
You will return to auth where you are asked to select a token with the green arrow button. If you want to use a different character, press the `LOG IN with EVE Online` button.
![select an SSO token to create with](/_static/images/features/apps/corpstats/select_sso_token.png)
If this works (and you have permission to view the Corp Stats you just created) you'll be returned to a view of the Corp Stats.
If it fails an error message will be displayed.
## Corp Stats View
### Navigation Bar
![navigation bar](/_static/images/features/apps/corpstats/navbar.png)
This bar contains a dropdown menu of all available Corporations. If the user has the `add_corpstats` permission, a button to add a Corp Stats will be shown.
On the right of this bar is a search field. Press enter to search. It checks all characters in all Corp Stats you have view permission to and returns search results.
### Last Update
![last update and update button](/_static/images/features/apps/corpstats/last_update.png)
An update can be performed immediately by pressing the update button. Anyone who can view the Corp Stats can update it.
### Character Lists
![lists](/_static/images/features/apps/corpstats/lists.png)
Three views are available:
- main characters and their alts
- registered characters and their main character
- unregistered characters
Each view contains a sortable and searchable table. The number of listings shown can be increased with a dropdown selector. Pages can be changed using the controls on the bottom-right of the table. Each list is searchable at the top-right. Tables can be re-ordered by clicking on column headings.
![table control locations](/_static/images/features/apps/corpstats/table_controls.png)
#### Main List
![main list](/_static/images/features/apps/corpstats/main_list.png)
This list contains all main characters in registered in the selected Corporation and their alts. Each character has a link to [zKillboard](https://zkillboard.com).
#### Member List
![member list](/_static/images/features/apps/corpstats/member_list.png)
The list contains all characters in the Corporation. Red backgrounds means they are not registered in auth. A link to [zKillboard](https://zkillboard.com) is present for all characters.
If registered, the character will also have a main character, main Corporation, and main Alliance field.
#### Unregistered List
![unregistered_list](/_static/images/features/apps/corpstats/unregistered_list.png)
This list contains all characters not registered on auth. Each character has a link to [zKillboard](https://zkillboard.com).
## Search View
![search results](/_static/images/features/apps/corpstats/search_view.png)
This view is essentially the same as the Corp Stats page, but not specific to a single Corporation.
The search query is visible in the search box.
Characters from all Corp Stats to which the user has view access will be displayed. APIs respect permissions.
## Permissions
To use this feature, users will require some of the following:
```eval_rst
+---------------------------------------+------------------+----------------------------------------------------+
| Permission | Admin Site | Auth Site |
+=======================================+==================+====================================================+
| corpstats.view_corp_corpstats | None | Can view corp stats of their corporation. |
+---------------------------------------+------------------+----------------------------------------------------+
| corpstats.view_alliance_corpstats | None | Can view corp stats of members of their alliance. |
+---------------------------------------+------------------+----------------------------------------------------+
| corpstats.view_state_corpstats | None | Can view corp stats of members of their auth state.|
+---------------------------------------+------------------+----------------------------------------------------+
| corpstats.add_corpstats | Can create model | Can add new corpstats using an SSO token. |
+---------------------------------------+------------------+----------------------------------------------------+
| corpstats.change_corpstats | Can edit model | None. |
+---------------------------------------+------------------+----------------------------------------------------+
| corpstats.remove_corpstats | Can delete model | None. |
+---------------------------------------+------------------+----------------------------------------------------+
```
Users who add a Corp Stats with their token will be granted permissions to view it regardless of the above permissions. View permissions are interpreted in the "OR" sense: a user can view their corporation's Corp Stats without the `view_corp_corpstats` permission if they have the `view_alliance_corpstats` permission, same idea for their state. Note that these evaluate against the user's main character.
## Automatic Updating
By default Corp Stats are only updated on demand. If you want to automatically refresh on a schedule, add an entry to your project's settings file:
```python
CELERYBEAT_SCHEDULE['update_all_corpstats'] = {
'task': 'allianceauth.corputils.tasks.update_all_corpstats',
'schedule': crontab(minute=0, hour="*/6"),
}
```
Adjust the crontab as desired.
## Troubleshooting
### Failure to create Corp Stats
>Unrecognized corporation. Please ensure it is a member of the alliance or a blue.
Corp Stats can only be created for Corporations who have a model in the database. These only exist for tenant corps,
corps of tenant alliances, blue corps, and members of blue alliances.
>Selected corp already has a statistics module.
Only one Corp Stats may exist at a time for a given Corporation.
>Failed to gather corporation statistics with selected token.
During initial population, the EVE Swagger Interface did not return any member data. This aborts the creation process. Please wait for the API to start working before attempting to create again.
### Failure to update Corp Stats
Any of the following errors will result in a notification to the owning user, and deletion of the Corp Stats model.
>Your token has expired or is no longer valid. Please add a new one to create a new CorpStats.
This occurs when the SSO token is invalid, which can occur when deleted by the user, the character is transferred between accounts, or the API is having a bad day.
>CorpStats for (corp name) cannot update with your ESI token as you have left corp.
The SSO token's character is no longer in the Corporation which the Corp Stats is for, and therefore membership data cannot be retrieved.
>HTTPForbidden
The SSO token lacks the required scopes to update membership data.

11
docs/features/apps/fleetactivitytracking.md Normal file
View File

@@ -0,0 +1,11 @@
# Fleet Activity Tracking
The Fleet Activity Tracking (FAT) app allows you to track fleet participation.
![fat](/_static/images/features/apps/fat.png)
## Installation
Fleet Activity Tracking requires access to the `esi-location.read_location.v1`, `esi-location.read_ship_type.v1`, and `esi-universe.read_structures.v1` SSO scopes. Update your application on the [EVE Developers site](https://developers.eveonline.com) to ensure these are available.
Add `'allianceauth.fleetactivitytracking',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.

96
docs/features/apps/hrapplications.md Normal file
View File

@@ -0,0 +1,96 @@
# HR Applications
This app allows you to manage applications for multiple corporations in your alliance. Key features include:
- Define application questionnaires for corporations
- Users can apply to corporations by filling outquestionnaires
- Manage review and approval process of applications
![hr](/_static/images/features/apps/hr.png)
## Installation
Add `'allianceauth.hrapplications',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.
## Management
### Creating Forms
The most common task is creating ApplicationForm models for corps. Only when such models exist will a Corporation be listed as a choice for applicants. This occurs in the Django admin site, so only staff have access.
The first step is to create questions. This is achieved by creating ApplicationQuestion models, one for each question. Titles are not unique.
Next step is to create the actual ApplicationForm model. It requires an existing EveCorporationInfo model to which it will belong. It also requires the selection of questions. ApplicationForm models are unique per Corporation: only one may exist for any given Corporation concurrently.
You can adjust these questions at any time. This is the preferred method of modifying the form: deleting and recreating will cascade the deletion to all received applications from this form which is usually not intended.
Once completed the Corporation will be available to receive applications.
### Reviewing Applications
Superusers can see all applications, while normal members with the required permission can view only those to their corp.
Selecting an application from the management screen will provide all the answers to the questions in the form at the time the user applied.
When a reviewer assigns themselves an application, they mark it as in progress. This notifies the applicant and permanently attached the reviewer to the application.
Only the assigned reviewer can approve/reject/delete the application if they possess the appropriate permission.
Any reviewer who can see the application can view the applicant's APIs if they possess the appropriate permission.
## Permissions
The following permissions have an effect on the website above and beyond their usual admin site functions.
```eval_rst
+---------------------------------------+------------------+----------------------------------------------------+
| Permission | Admin Site | Auth Site |
+=======================================+==================+====================================================+
| auth.human_resources | None | Can view applications and mark in progress |
+---------------------------------------+------------------+----------------------------------------------------+
| hrapplications.approve_application | None | Can approve applications |
+---------------------------------------+------------------+----------------------------------------------------+
| hrapplications.delete_application | Can delete model | Can delete applications |
+---------------------------------------+------------------+----------------------------------------------------+
| hrapplications.reject_applications | None | Can reject applications |
+---------------------------------------+------------------+----------------------------------------------------+
| hrapplications.view_apis | None | Can view applicant API keys, and audit in Jacknife |
+---------------------------------------+------------------+----------------------------------------------------+
| hrapplications.add_applicationcomment | Can create model | Can comment on applications |
+---------------------------------------+------------------+----------------------------------------------------+
```
Best practice is to bundle the `auth.human_resources` permission alongside the `hrapplications.approve_application` and `hrapplications.reject_application` permissions, as in isolation these don't make much sense.
## Models
### ApplicationQuestion
This is the model representation of a question. It contains a title, and a field for optional "helper" text. It is referenced by ApplicationForm models but acts independently. Modifying the question after it has been created will not void responses, so it's not advisable to edit the title or the answers may not make sense to reviewers.
### ApplicationForm
This is the template for an application. It points at a Corporation, with only one form allowed per Corporation. It also points at ApplicationQuestion models. When a user creates an application, they will be prompted with each question the form includes at the given time. Modifying questions in a form after it has been created will not be reflected in existing applications, so it's perfectly fine to adjust them as you see fit. Changing Corporations however is not advisable, as existing applications will point at the wrong Corporation after they've been submitted, confusing reviewers.
### Application
This is the model representation of a completed application. It references an ApplicationForm from which it was spawned which is where the Corporation specificity comes from. It points at a user, contains info regarding its reviewer, and has a status. Shortcut properties also provide the applicant's main character, the applicant's APIs, and a string representation of the reviewer (for cases when the reviewer doesn't have a main character or the model gets deleted).
### ApplicationResponse
This is an answer to a question. It points at the Application to which it belongs, to the ApplicationQuestion which it is answering, and contains the answer text. Modifying any of these fields in dangerous.
### ApplicationComment
This is a reviewer's comment on an application. Points at the application, points to the user, and contains the comment text. Modifying any of these fields is dangerous.
## Troubleshooting
### No corps accepting applications
Ensure there are ApplicationForm models in the admin site. Ensure the user does not already have an application to these Corporations. If the users wishes to re-apply they must first delete their completed application
### Reviewer unable to complete application
Reviewers require a permission for each of the three possible outcomes of an application, Approve Reject or Delete. Any user with the human resources permission can mark an application as in-progress, but if they lack these permissions then the application will get stuck. Either grant the user the required permissions or change the assigned reviewer in the admin site. Best practice is to bundle the `auth.human_resources` permission alongside the `hrapplications.approve_application` and `hrapplications.reject_application` permissions, as in isolation these don't serve much purpose.

17
docs/features/apps/index.md Normal file
View File

@@ -0,0 +1,17 @@
# Apps
**Alliance Auth** comes with a set of apps (also called plugin-apps) which provide basic functions useful to many organizations in Eve Online like a fleet schedule and a timerboard. This section describes which apps are available and how to install and use them. Please note that any app need to be installed before it can be used.
```eval_rst
.. toctree::
:maxdepth: 1
autogroups
corpstats
fleetactivitytracking
hrapplications
optimer
permissions_tool
srp
timerboard
```

9
docs/features/apps/optimer.md Normal file
View File

@@ -0,0 +1,9 @@
# Fleet Operations
Fleet Operations is an app for organizing and communicating fleet schedules.
![optimer](/_static/images/features/apps/optimer.png)
## Installation
Add `'allianceauth.optimer',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.

39
docs/features/apps/permissions_tool.md Normal file
View File

@@ -0,0 +1,39 @@
# Permissions Auditing
Access to most of Alliance Auth's features are controlled by Django's permissions system. In order to help you secure your services, Alliance Auth provides a permissions auditing tool.
This is an optional app that needs to be installed.
To install it add `'allianceauth.permissions_tool',` to your `INSTALLED_APPS` list in your auth project's settings file.
## Usage
### Access
In order to grant users access to the permissions auditing tool they will need to be granted the `permissions_tool.audit_permissions` permission or be a superuser.
When a user has access to the tool they will see the "Permissions Audit" menu item under the "Util" sub menu.
### Permissions Overview
The first page gives you a general overview of permissions and how many users have access to each permission.
![permissions overview](/_static/images/features/apps/permissions_tool/overview.png)
**App**, **Model** and **Code Name** contain the internal details of the permission while **Name** contains the name/description you'll see in the admin panel.
**Users** is the number of users explicitly granted this permission on their account.
**Groups** is the number of groups with this permission assigned.
**Groups Users** is the total number of users in all of the groups with this permission assigned.
Clicking on the **Code Name** link will take you to the [Permissions Audit Page](#permissions-audit-page)
### Permissions Audit Page
The permissions audit page will give you an overview of all the users who have access to this permission either directly or granted via group membership.
![permissions audit](/_static/images/features/apps/permissions_tool/audit.png)
Please note that users may appear multiple times if this permission is granted via multiple sources.

9
docs/features/apps/srp.md Normal file
View File

@@ -0,0 +1,9 @@
# Ship Replacement
Ship Replacement helps you to organize ship replacement programs (SRP) for your alliance.
![srp](/_static/images/features/apps/srp.png)
## Installation
Add `'allianceauth.srp',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.

9
docs/features/apps/timerboard.md Normal file
View File

@@ -0,0 +1,9 @@
# Structure Timers
Structure Timers helps you keep track of both offensive and defensive structure timers in your space.
![timerboard](/_static/images/features/apps/timerboard.png)
## Installation
Add `'allianceauth.timerboard',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.