~~NOTOC~~ ====== Overview of the Fossology User Interface ====== This chapter provides an overview of the Fossology User Interface (UI). Detailed descriptions of Fossology's functions are provided in additional sections of Fossology documentation, which can be accessed from the [[user_documentation|User Docs]] contents page. ===== Fossology User Interface - Initial Screen ===== The Fossology User Interface (UI) initial screen is shown below. When you first access the Fossology UI - limited functionality is available until you log in to the interface. An example of the initial Fossology screen is shown below. Note that some of the menu tabs at the top of the sceen are grayed-out, indicating that they are not accessible. {{ui-menu-loggedout.png|}} \\ The functions that are provided to users who are not logged-in are: * Home - return to Home page * Search - search the uploaded projects for specific files * Browse - browse the currently uploaded projects * Help - get help using Fossology * Login - log in to the full Fossology UI Click on a topic above for detailed information about that topic. \\ Once you have logged in to the Fossolgy UI, you can access Fossology's full functionality, as described in the following sections. \\ \\ ===== Logging In to the UI ===== You can log in to the Fossology UI by clicking on the highlighted **login** item on the right side of the screen. \\ The following login screen is displayed. {{ui-menu-logging-in.png|}} \\ Fill in the username/password information and then click the {{login-button.png|}} button at the bottom of the screen. \\ //**Notes: **// * Prior to being able to log in, you must posses an account on the Fossology system. * **Username** and **Password** are required, **Validate IP** is optional. \\ \\ ===== Fossology User Interface - After Logging In ===== After you log in to the Fossology user interface, the following screen is displayed. Note that the menu tabs at the top of the sceen are no longer grayed-out. You now have access to all functionality of the UI. {{ui-menu-loggedin.png|}} \\ \\ \\ ===== Finding Files Using Search ===== Select the **Search** tab in the top menu to access the search screen. If you know the name, or part of the name, of a file, you can search for it within the Fossology Repository using the search mechanism on this screen. Enter the search information into the text box, and click the **Search** button underneath it, to initiate a search. {{ui-menu-search-v1.png|}} \\ \\ \\ If you select the **Advanced** search feature, additional search capabilities are provided, as shown in the following screen example: {{ui-menu-search-advanced.png|}} ===== Finding License Information Using Browse ===== The **Browse** tab provides a means of displaying analyzed license information in the fossology Respository. An example of the Browse screen is provided below. Note that the **Browse** screen provides folder navigation in the left-side window, and upload information in the right-side window. By clicking on a folder and then on an upload, you can browse the repository and navigate to license information. Refer to the following documentation for detailed information about using the **Browse** functionality. * [[How to Browse the Data-Base]] explains some basics about using the **Browse** functionality. * [[How to Find Analyzed License Information]] explains how to navigate through the license information provided by **Browse**. * [[How to Interpret the License Analysis Report]] explains how to interpret license analysis information. {{ui-menu-browse-v1.png|}} \\ \\ \\ ===== Uploading Files to Analyze ===== FOSSology has many options for importing and uploading files for analysis. \\ These options can be accessed from the **Upload** tab in the Fossology UI. {{ui-menu-upload-v1.png|}} \\ The options vary based on where the data to upload is located. The data can be uploaded from: * Your browser system - Use the **Upload > from File** option to select and upload the file. While this can be very convenient (particularly if the file is not readily accessible online), uploading via your web browser can be slow for large files, and files larger than 650 Megabytes may not be uploadable. * The FOSSology web server. Use the **Upload > from Server** option to specify a file or path on the web server. This option is intended for developers who have mounted directories containing source trees. The directory must be accessible via the web server's user. * A remote server - Use the **Upload > from URL** option to specify a remote server. This is the most flexible option, but the URL must denote a publicly accessible HTTP, HTTPS, or FTP location. URLs that require authentication or human interactions cannot be downloaded through this automated system. Use the **Upload > One-Shot License** option to upload a single file for license analysis. The analysis is done in real-time. Note the limitations that are listed on the **One-Shot License Analysis** screen. If your system is configured to use multiple agent servers, the data area must be mounted and accessible to the FOSSology user (fossy) on every agent system. See the section [[scheduler#Configuring the Scheduler]] in the [[Scheduler]] documentation. \\ \\ ===== Organizing Fossology Data ===== Fossology provides many options for organizing license data and uploads. \\ You can access these options from the **Organize** tab in the Fossology UI. {{ui-menu-organize-v1.png|}} \\ \\ \\ ==== Organizing Folders ==== In the **Organize > Folders** submenu, you can Create, Delete, Edit, and Move folders. {{ui-menu-organize-folders-v1.png|}} \\ \\ \\ ==== Creating and Organizing License Groups and Terms ==== License Groups provide organization for the license information in the Fossology Repository. License Terms associate common license names with canonical license names. \\ In the **Organize > Licenses** submenu, you can create and manage groups of licenses, and create and manage license terms. Fossology also provides the ability within this menu to create some default license groups and terms. Use **Organize > Licenses > Default Groups** to create default license groups. Use **Organize > Licenses > Manage Groups** to manage license groups. Use **Organize > Licenses > Default Terms** to create default license terms. Use **Organize > Licenses > Manage Terms** to manage license terms. {{ui-menu-organize-license-v1.png|}} \\ \\ \\ ==== Organizing Uploads ==== The **Organize > Uploads** submenu provides the ability to delete uploaded files, move uploaded files, edit the properties of uploaded files, and to remove the license analysis of uploaded files. {{ui-menu-organize-uploads-v1.png|}} \\ \\ \\ ===== Managing Jobs on the System ===== The **Jobs** menu is used to manage Fossology jobs and access Fossology job information. Within this menu, you can schedule an uploaded file for license analysis, and you can follow the progress of the analysis. [[How to Interpret the Job Queue]] provides a description about interpreting and using the information provided by the **Jobs** functions. {{ui-menu-jobs.png|}} \\ \\ \\ ==== Scheduling an Analysis ==== The **Jobs>Agents** menu item provides access to the various Fossology agents that perform the license analysis of files that have been uploaded to the Fossology Repository. In addition to scheduling a general license analysis, there are several specific types of analysis that can be performed. {{ui-menu-jobs-agents.png|}} \\ \\ ==== Analyzing ==== FIXME This menu item has not yet been activated. {{ui-menu-jobs-analyze.png|}} \\ \\ ==== Getting Job Queue Information ==== The **Jobs > Queue** menu provides access to job information in the following ways: * Job queue summary - See a short summary of jobs. * Job queue details - See detailed information about jobs. * Job queue information by upload - See scheduled jobs associated with an uploaded file. The following fossology job information is provided: * Jobs that are Queued * Jobs that are Scheduled * Jobs that are Running * Jobs that are Finished * Jobs that are Blocked * Jobs that are Failed {{ui-menu-jobs-queue.png|}} \\ \\ ===== Performing Administrative Functions ===== {{ui-menu-admin.png|}} \\ \\ ==== Dashboard ==== **Dashboard** provides a quick, useful overview of Job Queue, Database Contents, Repository Disk Space, and Database Metrics. {{ui-menu-admin-dashboard-v1.png|}} \\ When you select **Admin > Dashboard**, as shown above, the following screen is displayed. Note that the **Job Queue** information provides links to additional information. {{ui-menu-admin-dashboard-screen-v1.png|}} \\ \\ ==== Database Administration ==== Checking the Database, Database performance \\ {{ui-menu-admin-database-v1.png|}} \\ \\ \\ === Checking the Database for Inconsistencies === On occasion, the database can become inconsistent. For example, there may be pfile records without ufile entries, or ufile entries that are not linked by any uploadtree records. Inconsistencies usually arise due to failed unpacking, partial deletions, and testing. \\ Temporary inconsistencies may exist when a file is uploaded, being unpacked, or being deleted. * An uploaded file -- before being unpacked -- can appear inconsistent. * The unpack system creates ufiles and pfiles first, then links them together when it completes. * The delete system removes records in series, so a partial delete (or delete in progress) can show inconsistencies. **Admin > Database > Check** provides information about tasks running in the job queue that may make records appear inconsistent. **Admin > Database > Check Templates ** provides information about license templates that require cleaning-up, and provides clean-up capabilities. \\ \\ === Improving Database Performance === Database performance can be improved by optimizing table memory allocation. The database supports two methods: * **vacuum** to free deleted rows * **analyze** to precompute row counts These two functions are called by most agents on an as-needed basis. However, you can also start them yourself when needed. \\ Keep in mind that running these functions too often can also negatively impact database performance, since the database will spend more time cleaning than doing real work. **Admin > Database > Vacuum and Analyze** provides access to these functions. \\ \\ === Viewing, Exporting, and Applying Database Schema === **Admin > Database > Schema ** is only used for installation and debugging purposes. Otherwise, you should not need to use this functionality. It is strongly advised that you do not use **Schema** functionality unless you are a very experienced FOSSology administrator and know exactly what you are doing. __**WARNING!** Improper use of this functionality can destroy your FOSSology database!__ ==== Viewing Agent Status ==== You can view the Show Agent Status screen by selecting Admin > Scheduler> Status. \\ {{ui-menu-admin-scheduler.png|}} {{ui-menu-admin-scheduler-status-screen.png|}} \\ \\ ==== Administering Users ==== **Admin > Users** provides a means of user account administration. You can add or delete users, edit user account information, and set various user-specific security and access paramaters. {{ui-menu-admin-users.png|}} \\ \\ \\ ===== Getting Help ===== The **Help** menu provides several topics about the Fossology user interface. Also included in this menu, under **Help > Debug** are various Fossology debugging options. {{ui-menu-help.png|}}