Global and Project Scopes
When building an app for YouTrack, it's important to understand the distinction between global and project scopes. These scopes determine the level at which features, settings, and extensions are available within the system.
Scopes for Extension Points
Each extension point for an app is designed to work at the global scope or project scope.
An extension point with a global scope is available throughout the system. This means it can be accessed by users outside the context of a specific project.
An extension point with a project scope is limited to a particular project. Widgets that use these extension points are only available in the context of a project where the app has been attached and the widget is active. Users will only have access to the widget if they have access to the project as well.
The following extension points have a global scope:
ADMINISTRATION_MENU_ITEM
DASHBOARD_WIDGET
MAIN_MENU_ITEM
MARKDOWN
USER_CARD
USER_PROFILE_SETTINGS
These extension points have a project scope:
ARTICLE_OPTIONS_MENU_ITEM
ISSUE_ABOVE_ACTIVITY_STREAM
ISSUE_BELOW_SUMMARY
ISSUE_FIELD_PANEL_LAST
ISSUE_FIELD_PANEL_FIRST
ISSUE_OPTIONS_MENU_ITEM
PROJECT_SETTINGS
HELPDESK_CHANNEL
For more information about extension points, see Extension Points.
Scopes for HTTP Handlers
The same concept applies to HTTP handlers, which are also accessible either at the global or project level.
HTTP handlers with the following endpoints are scoped at the global level:
global
user
HTTP handlers with the following endpoints are scoped at the project level:
issue
article
project
With HTTP handlers, you cannot mix global-level and project-level endpoints in a single handler. Any app that contains HTTP handlers that define endpoints for multiple scopes will be rejected by YouTrack. If you want to define custom endpoints for multiple scopes in a single app, use separate HTTP handlers for each scope.
When you attach an app that contains global-level HTTP handlers to a project, it doesn't change the scope for the endpoint. These global endpoints are still available at the system level even if they appear to be switched off using the visibility settings for the app itself.
Project-level handlers, on the other hand, must be activated per-project and are only accessible in the projects where the app has been attached and the module that contains the HTTP handler is active.
HTTP handler scopes also affect who has permission to manage modules for the app.
Modules that contain HTTP handlers for global-level endpoints can only be managed by users with the Low-level Admin Write permission. This permission is usually reserved for system administrators.
If a user who doesn't have Low-level Admin Write permission installs or imports an app that contains a global module, the app will be deactivated automatically. It can only be activated by a user who has sufficient permissions.
Modules that only contain HTTP handlers for project-level endpoints can be managed by users with Update Project permission.
Users with Update Project permission are not allowed to replace the endpoint for a project-scoped HTTP handler with an endpoint that requires a global scope.
For more information about HTTP handlers for YouTrack apps, see HTTP Handlers.