From c94554eebc7eb16f9240c1c5be2e66d5c3da18b4 Mon Sep 17 00:00:00 2001 From: Christopher Burr Date: Thu, 25 Jan 2024 09:54:59 +0000 Subject: [PATCH 01/35] update documentation --- site/docs/guidance/index.md | 12 +- .../assurance-ecosystem.md | 26 ++ site/docs/introductory-resources/index.md | 12 +- site/docs/introductory-resources/standards.md | 259 ++++++++++++++++++ site/drafts/standards.md | 17 -- site/drafts/why-is-assurance-important.md | 31 --- 6 files changed, 304 insertions(+), 53 deletions(-) create mode 100644 site/docs/introductory-resources/standards.md delete mode 100644 site/drafts/standards.md delete mode 100644 site/drafts/why-is-assurance-important.md diff --git a/site/docs/guidance/index.md b/site/docs/guidance/index.md index 1047dcad..64315b87 100644 --- a/site/docs/guidance/index.md +++ b/site/docs/guidance/index.md @@ -4,6 +4,16 @@ tags: - Introductory Resource --- -!!! info "Draft" +!!! warning "Draft" This section is being drafted. + +In this section you will find the main documentation and user guidance for the TEA platform. +For those who are completely new to the platform, we recommend you follow these guides in order : + +1. Getting started with the TEA platform (*in progress*) +2. Building an assurance case (*in progress*) +3. [Components of an assurance case](components.md) +4. Managing and sharing assurance cases (*in progress*) + +You can also find more advanced documentation (e.g. deployment instructions, API documentation) in our [platform details](../platform-details/about.md) section. diff --git a/site/docs/introductory-resources/assurance-ecosystem.md b/site/docs/introductory-resources/assurance-ecosystem.md index 901bb1b0..aa1615d5 100644 --- a/site/docs/introductory-resources/assurance-ecosystem.md +++ b/site/docs/introductory-resources/assurance-ecosystem.md @@ -25,6 +25,32 @@ AI technologies and maximise their opportunities. The following is based on and adapted from the Centre for Data Ethics and Innovation's AI Assurance Guide, which extends their original roadmap and seeks to clarify the scope of an assurance ecosystem as it pertains to AI. We consider some of the core concepts of the CDEI's guide, focusing on the parts that are relevant to the TEA platform. For further information, please visit their site: [https://cdeiuk.github.io/ai-assurance-guide/](https://cdeiuk.github.io/ai-assurance-guide/) +## Why is Assurance Important + +Data-driven technologies, such as artificial intelligence, have a complex +lifecycle. In some cases, this complexity is further heightened by the scale at +which a system is deployed (e.g. social media platforms with international +reach). + +The scale and complexity of certain data-driven technologies has already been +clearly communicated by others, such as +[this excellent infographic](https://anatomyof.ai) from the AI Now Institute +showing the many societal impacts and touch points that occur in the development +of Amazon’s smart speaker. Therefore, it is not necessary to revisit this point +here. However, it is important to explain why this complexity and scale matters +for the purpose of trustworthy and ethical assurance. There are three +(well-rehearsed) reasons that are salient within the context of the assurance +ecosystem: + +1. Complexity: as the complexity of a system increases it becomes harder to + maintain transparency and explainability. +2. Scalability: the risk of harm increases proportional to the scale of a + system, and mechanisms for holding people or organisations accountable become + harder to implement. +3. Autonomous behaviour: where data-driven technologies are used to enable + autonomous behaviour, opportunities for responsible human oversight are + reduced. + ## Justified Trust As discussed at the start of this section, assurance is about building trust. diff --git a/site/docs/introductory-resources/index.md b/site/docs/introductory-resources/index.md index 1047dcad..f1201bc4 100644 --- a/site/docs/introductory-resources/index.md +++ b/site/docs/introductory-resources/index.md @@ -1,9 +1,13 @@ --- -status: draft tags: - - Introductory Resource + - Introductory Resources --- -!!! info "Draft" +In this section you will find the following resources. +The guides can be read in any order and independently of each other, but the following order is recommended for those who are completely new to the area: - This section is being drafted. +- [What is Trustworthy and Ethical Assurance?](what-is-tea.md): an introduction to the Trustworthy and Ethical Assurance framework +- [An Introduction to Argument-Based Assurance](argument-based-assurance.md): a short guide on the framework of argument-based assurance that underpins TEA +- [Understanding the Assurance Ecosystem](assurance-ecosystem.md): an introduction to the broader AI assurance ecosystem +- [Standards and their role in assurance](standards.md): an introduction to standards, the different types of standards and their role in assurance +- [Open Challenges](open-challenges.md): a set of open challenges and research questions for TEA and assurance more generally. diff --git a/site/docs/introductory-resources/standards.md b/site/docs/introductory-resources/standards.md new file mode 100644 index 00000000..1db9d6ef --- /dev/null +++ b/site/docs/introductory-resources/standards.md @@ -0,0 +1,259 @@ +--- +authors: + - Shakir Laher + - Christopher Burr +--- + +# Standards and their role in assurance + +!!! info "AI Standards Hub" + + This guidance has been co-produced alongside the [AI Standards Hub](https://aistandardshub.org/)—a UK initiative dedicated to the evolving and international field of standardisation for AI technologies, hosted at the Alan Turing Institute and supported by BSI, NPL, and HM Government. + +## What are standards? + +A 'standard' can be described as rules, requirements, norms or guidelines, that are established for application within certain contexts and settings. +We see examples of this in, industry, academia, professions, products and services, to establish standardised processes as part of governance and assurance frameworks. + +Standards are developed in a variety of ways, although the best-practice approach to their formation and the most widely accepted are essentially standards crafted through *consensus-building processes*. +These standards can be developed and led by, for example, academic institutions, international bodies, professional associations, industry or formally recognised Standards Development Organisations (SDOs)/[^sdos] + +[^sdos]: Also see [https://aistandardshub.org/resource/main-training-page-example/1-what-are-standards/](https://aistandardshub.org/resource/main-training-page-example/1-what-are-standards/). + +Standards developed by SDOs are often referred to as 'technical standards'. +These standards are developed by stakeholder-driven processes that are guided by principles such as relevance, transparency, and consensus. +Standards on the whole are voluntary but can be formally recognised in regulations and international treaties, especially those developed by SDOs. +Furthermore, they can be tools used as part of compliance towards governance and assurance frameworks. + +Standards can be in a variety of forms but commonly are established and disseminated as documents approved by a recognised body. +They provide common and repeatable rules, requirements, norms, guidelines and characteristics for activities that will lead to their associated outcomes; and are aimed at providing order in the contexts where they are applied. + +## Different types of standards + +Standards find application across diverse domains and sectors. +They serve to encode technical specifications related to the measurement, design, or performance of products and systems. +Additionally, standards extend their influence to evaluating the impacts or efficiency of broader processes or services. + +While some standards are uncomplicated, offering clear metric definitions (e.g. the standardised format of A4 and related paper sizes adopted globally), others offer guidance on intricate, context-specific processes. + +Below are some of the categories of standards available. + +!!! info "Types of Standards" + +- [Foundational and terminological](#foundational-and-terminological) +- [Process, management, and governance](#process-management-and-governance) +- [Measurement and test methods](#measurement-and-test-methods) +- [Product and performance requirements](#product-and-performance-requirements) +- [Interface and architecture](#interface-and-architecture) + +### Foundational and terminological + +Foundational and terminological standards provide shared vocabularies, terms, descriptions and definitions, enabling effective communication and fostering collaboration between stakeholders on a given shared area of interest. +They help improve understanding between stakeholders through the shared common language at their disposal by setting out agreed-upon terms and definitions. +These standards often form the baseline language utilised in other standards supporting their development and forming bilateral relationships. + +:::success +**Examples** + +- ISO/IEC 22989 BS ISO/IEC 22989:2022 Information technology – Artificial intelligence – Artificial intelligence concepts and terminology + - This document establishes terminology for AI and describes concepts in the field of AI. This document can be used in the development of other standards and in support of communications among diverse, interested parties or stakeholders. This document is applicable to all types of organizations (e.g. commercial enterprises, government agencies, not-for-profit organizations). + - [AI Standards Hub Link](https://aistandardshub.org/ai-standards/information-technology-artificial-intelligence-artificial-intelligence-concepts-and-terminology-2/) +- ISO/IEC TS 5723 PD ISO/IEC TS 5723:2022 Trustworthiness – Vocabulary + - This document provides a definition of trustworthiness for systems and their associated services, along with a selected set of their characteristics. + - [AI Standards Hub Link](https://aistandardshub.org/ai-standards/trustworthiness-vocabulary/) + +::: + +### Process, management, and governance + +Process and management standards assist organisational processes and approaches to follow well defined steps to achieve their aims and objectives. +These standards are in-place to guide areas such as; quality assurance, risk management, management systems, benchmarking and regulatory compliance. + + + +### Measurement and test methods + +Measurement and test standards are designed to set out repeatable methodologies and requirements to test attributes (e.g., security, safety, etc) of systems which are underpinned by units of measurement and associated metrics for performance and testing standards. +These standards ensure specified thresholds have been achieved and enable entities applied under their remit to possess trustworthiness qualities. +For communication amongst stakeholders, these standards provide clarity and a shared understanding of tests and measurement requirements, enabling precise and meaningful communication across discrete sectors, domains and scientific disciplines, whose tests and measurement requirements differ. +The aviation industry is one example where they are relied upon to achieve acceptably safe and trustworthy aircraft. + + + +### Product and performance requirements + +Product and performance standards play a multifaceted role across industries, serving as vital tools for quality assurance, consumer protection, and regulatory compliance. +These standards establish specific criteria to ensure that products and services meet defined benchmarks, safeguarding consumers by setting safety and performance requirements. +Facilitating international trade, standards provide a common ground for product specifications, enabling consistency and smooth trade relations between countries. +Beyond regulatory requirements, adherence to recognised standards fosters innovation, serving as a foundational reference for research and development efforts. +The efficiency and productivity of organisations are significantly enhanced as standards streamline processes, reducing errors and improving overall workflow. +They also play a crucial role in risk management, helping organisations identify and mitigate potential risks associated with their products and processes. +Compliance with standards builds public trust, as consumers are more inclined to rely on products and services adhering to recognised criteria. +Additionally, this set of standards contribute to safety assurance, particularly in industries where safety is paramount, by preventing accidents and protecting consumers and users. +These standards are instrumental in shaping reliable, safe, and high-quality products, contributing to the advancement and credibility of various industries. + + + +### Interface and architecture + +Interoperability, infrastructure, architecture, and data management and compatibility standards define common protocols, formats, and interfaces to ensure that diverse elements within a system or across systems can exchange data and functionality effectively between platforms and architectures. + + + +## Functions and benefits of standards + +Standards, as functional tools, can play a pivotal role in realising a wide array of benefits across many domains and sectors. +They ensure consistency and uniformity; provide a common language and set of guidelines for processes, products, or services; and help to systematically manage risks and unlock potential. +This consistency enhances communication, reduces misunderstandings, creates trust and fosters a shared understanding among stakeholders. +They are increasingly relied upon when implementing assurance frameworks to provide the specificity required to assure the quality and safety. +This leads to increased efficiency and innovative edge to stay current and competitive in the global marketplace. + +The following headings highlight the functions and benefits in more detail: + +- [Assurance, risks, and trust](#assurance-risks-and-trust) +- [Knowledge and technology diffusion](#knowledge-and-technology-diffusion) +- [Standards as compliance tools](#standards-as-compliance-tools) + +### Assurance, risks, and trust + +The paramount concern for organisations engaged in technology production is the safety and quality of their products. +This concern extends to the individuals who adopt, use, and are affected by these technologies. +Standards serve as a cornerstone, enabling organisations to attain high-quality products and effectively manage associated risks by integrating them into their assurance systems. +These standards become integral components of conformity assessments, allowing organisations to demonstrate that their technologies and services not only meet safety, ethical, and legal requirements but also contribute to enhancing their reputation and fostering public trust. +Noteworthy examples like [DCB 0129/0160](https://www.england.nhs.uk/long-read/digital-clinical-safety-assurance/) exemplify how standards, such as those integrated into the clinical safety assurance framework of the NHS in England, play a pivotal role in upholding safety standards and ensuring the quality of technologies within the healthcare sector. + +By establishing benchmarks for the quality of products, services, or processes, standards help organisations maintain high standards of excellence. +Consumers, in turn, gain confidence in products that adhere to recognised standards, knowing that they meet specified criteria for safety, reliability, and performance. +Additionally, standards contribute to cost savings and efficiency by streamlining processes, reducing errors, and optimising resource utilisation. + +### Knowledge and technology diffusion + +Standards and their development processes provide an infrastructure for the transfer of knowledge and technology within society and the economy. +The consensus-building processes inherent in standards development are particularly noteworthy, as they facilitate the translation of research and best practices into accessible, practical guidance. +Furthermore, through these consensus-building processes, standards development forums bring together experts, stakeholders, and representatives from various sectors. +This collaborative effort ensures that a broad spectrum of perspectives is considered, leading to the creation of standards that reflect a shared understanding of best practices. +As a result, organisations can leverage these standards to enhance their operational processes and bring products to market that demonstrate trustworthy properties. + +By bridging the gap between research and practical application, standards become instrumental in driving improvements in operational efficiency and the overall quality of products entering the commercial sphere. +They provide a structured pathway for the integration of advancements from diverse fields into the fabric of everyday operations, ultimately contributing to the advancement of technology, innovation, and the betterment of society and the economy at large. + +### Standards as compliance tools + +Certain standards are explicitly endorsed by regulatory authorities as essential tools for organisations to meet the requirements outlined in regulations. +In the UKs regulatory framework, relevant Secretaries of State have the authority to 'designate' specific standards for the purpose of regulatory conformity. +When a standard is officially designated by the government, its adoption carries a significant weight—it essentially presumes that organisations adhering to this standard are in compliance with the pertinent aspects of regional regulations. +In essence, organisations that have followed a designated standard are presumed to be in compliant with the relevant regulatory requirements. +This mechanism mirrors similar practices in other jurisdictions, such as the European Union (EU), where 'harmonised' standards play an analogous role in establishing and ensuring regulatory conformity. + +## Standards and Trustworthy and Ethical Assurance + +With the types of standards and their functions and benefits now outlined, we can also ask 'what role do standards have in the TEA framework'? +And, what other connections are there between TEA and standards? + +??? info "Reminder of the Types of Standards" + + - Foundational and terminological + - Interface and architecture + - Measurement and test methods + - Process, management, and governance + - Product and performance requirements + +Using the types of standards as a reference, we can identify the following roles for standards in the TEA framework:[^ecosystem] + +[^ecosystem]: Standards may also have additional roles in the context of the broader [assurance ecosystem](assurance-ecosystem.md). + +### Supporting development of assurance case structure + +Several types of standards can support the development of an assurance case's structure. +For instance, `foundational and terminological` standards can be useful for identifying core attributes for a top-level goal claim, which in turn would allow a project team to develop strategies for each of the core attributes. +And, `process, management, and governance` standards could help a team or organisation develop a project governance plan that integrates considerations of the iterative development of an assurance case (e.g. ML safety requirements as set out in the AMLAS guidance[^amlas]). +These standards can also ensure that the assurance case adheres to industry best practices, thereby enhancing its credibility and acceptance. + +[^amlas]: Hawkins, R., Paterson, C., Picardi, C., Jia, Y., Calinescu, R., & Habli, I. (2021). Guidance on the Assurance of Machine Learning in Autonomous Systems (AMLAS). University of York. https://www.york.ac.uk/media/assuring-autonomy/documents/AMLASv1.1.pdf + + + +### Evidential grounding and justification of property claims + +Property claims require evidential grounding. +That is, the validity of a claim needs to be justified by connecting the claim to evidence through a `supported by` link (see [guidance](../guidance/components/#support-links)). +But how does a project team or organisation know which evidence to select, and whether it is sufficient to justify the claims being made? This is where standards can provide useful support? + +For instance, `measurement and test methods` and `product and performance requirements` standards are crucial for determining whether a system meets the required performance levels. +They can also help set out criteria or benchmarks for determining which forms of evidence are sufficient (e.g. objective and quantitative criteria for compliance) or how the evidence should be gathered, documented, and managed (e.g. communication of uncertainty when dealing with probabilistic evidence). + +!!! note "The Use of Artificial Intelligence in Health Care: Trustworthiness (ANSI/CTA-2090)" + + ANSI/CTA-2090 is one example of a standard that sets out requirements for several core attributes related to human, technical, and regulatory trust. For instance, their approach to bias includes (but is not limited to) the following requirements for the model developer and owner of the AI solution: + + - Determine if the existing data set are “raw” data or pre-processed data. + - For pre-processed data, find out what kind(s) of pre-processing has been performed so that the same preprocessing software/method can be applied to the input data during inference. + - If there is need to capture additional new data, it is important to know how the existing data was collected (e.g., hardware/sensor, environment condition) so that the new data can be collected under similar conditions. + - When combining or joining multiple existing data sets: + - Learn and/or model the bias for each data set. + - Mitigate or undo the associated bias from each data set. + - Find out the commonalities to all the data sets (e.g., through modeling) to achieve cross-dataset generalization. + - When splitting a collected data set into training, validation, and testing datasets, make sure each of them is randomly selected by applying certain techniques (e.g., data shuffling with a random number generator). By doing so, it can reduce the potential bias introduced in this process. + + + +### Building trust among stakeholders + +For systems that interact with other systems or operate within a larger ecosystem, `process, management, and governance` standards can ensure compatibility or interoperability of data. +This can be vital in situations where groups of stakeholders are making choice about whether to invest or interact with a specific ecosystem or platform (e.g. digital twins). +Here, providing assurance (through reference to an accepted standard) can build confidence among the stakeholders (or possible stakeholders) within the ecosystem. +Such an example extends beyond goals such as interoperability though. +Concerns such as data quality, security and privacy, liability and accountability, can also impact the trustworthiness of a system. +As such, communication through structured assurance cases that reference key standards can help build trust. + +#### Knowledge transfer and consensus formation + +Where standards exist at an early (and perhaps incomplete) stage of development, or perhaps do not exist at all (e.g. when dealing with novel data-driven technologies), assurance cases can serve as a useful reference for how different teams and sectors understand sufficiency and justifiability. +Consider a situation where an assurance claim regarding a property of a system cannot be sufficiently evidenced. +This does not necessarily mean it is false. +Rather, it could indicate a gap where standards do not yet exist. +In this sense, open assurance cases can support the formation of consensus and the development of best practices and community-based standards. + +For instance, several teams within a shared community of practice (e.g. explainability of AI systems for environmental science) may choose to share their assurance cases with each other through structured knowledge share events (e.g. workshops). In doing so, they could identify common claims that depend on the same forms of `evaluative` evidence (e.g. usability testing and related human factors research). Furthermore, they may be able to identify areas where their design choices will limit `interoperability` in the broader ecosystem, and on this basis revisit their system requirements. + + + +!!! abstract "Further Resources" + + For more information on standards, see the following resources: + + - The AI Standards Hub has a range of training materials included in their training database: [https://aistandardshub.org/training-search/](https://aistandardshub.org/training-search/) + - The British Standards Institute (BSI) has a knowledge base with articles and news related to a wide array of standards: [https://knowledge.bsigroup.com/](https://knowledge.bsigroup.com/) diff --git a/site/drafts/standards.md b/site/drafts/standards.md deleted file mode 100644 index a7a9feed..00000000 --- a/site/drafts/standards.md +++ /dev/null @@ -1,17 +0,0 @@ -# Standards and their role in assurance - -## What are standards? - -<-- Shakir to draft first version --> - -- Different types of standards -- Functions and benefits of standards -- Types of standards at points in the lifecycle - -## Role of standards in the assurance ecosystem - -<-- Speak with Nuala about reusing/repurposing CDEI work --> - -## Standards and claims, evidence, and strategies - -<-- CB to take first draft --> diff --git a/site/drafts/why-is-assurance-important.md b/site/drafts/why-is-assurance-important.md deleted file mode 100644 index d82a2709..00000000 --- a/site/drafts/why-is-assurance-important.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -status: draft -tags: - - Introductory Resource ---- - -# Why is Assurance Important? - -Data-driven technologies, such as artificial intelligence, have a complex -lifecycle. In some cases, this complexity is further heightened by the scale at -which a system is deployed (e.g. social media platforms with international -reach). - -The scale and complexity of certain data-driven technologies has already been -clearly communicated by others, such as -[this excellent infographic](https://anatomyof.ai) from the AI Now Institute -showing the many societal impacts and touch points that occur in the development -of Amazon’s smart speaker. Therefore, it is not necessary to revisit this point -here. However, it is important to explain why this complexity and scale matters -for the purpose of trustworthy and ethical assurance. There are three -(well-rehearsed) reasons that are salient within the context of the assurance -ecosystem: - -1. Complexity: as the complexity of a system increases it becomes harder to - maintain transparency and explainability. -2. Scalability: the risk of harm increases proportional to the scale of a - system, and mechanisms for holding people or organisations accountable become - harder to implement. -3. Autonomous behaviour: where data-driven technologies are used to enable - autonomous behaviour, opportunities for responsible human oversight are - reduced. From 80f7e340ebfc8e1986c3750c2f50ad7f429b4811 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 25 Jan 2024 09:57:48 +0000 Subject: [PATCH 02/35] style: pre-commit fixes --- site/docs/introductory-resources/standards.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/site/docs/introductory-resources/standards.md b/site/docs/introductory-resources/standards.md index 1db9d6ef..41036838 100644 --- a/site/docs/introductory-resources/standards.md +++ b/site/docs/introductory-resources/standards.md @@ -13,12 +13,12 @@ authors: ## What are standards? A 'standard' can be described as rules, requirements, norms or guidelines, that are established for application within certain contexts and settings. -We see examples of this in, industry, academia, professions, products and services, to establish standardised processes as part of governance and assurance frameworks. +We see examples of this in, industry, academia, professions, products and services, to establish standardised processes as part of governance and assurance frameworks. Standards are developed in a variety of ways, although the best-practice approach to their formation and the most widely accepted are essentially standards crafted through *consensus-building processes*. -These standards can be developed and led by, for example, academic institutions, international bodies, professional associations, industry or formally recognised Standards Development Organisations (SDOs)/[^sdos] +These standards can be developed and led by, for example, academic institutions, international bodies, professional associations, industry or formally recognised Standards Development Organisations (SDOs)/[^sdos] -[^sdos]: Also see [https://aistandardshub.org/resource/main-training-page-example/1-what-are-standards/](https://aistandardshub.org/resource/main-training-page-example/1-what-are-standards/). +[^sdos]: Also see [https://aistandardshub.org/resource/main-training-page-example/1-what-are-standards/](https://aistandardshub.org/resource/main-training-page-example/1-what-are-standards/). Standards developed by SDOs are often referred to as 'technical standards'. These standards are developed by stakeholder-driven processes that are guided by principles such as relevance, transparency, and consensus. @@ -26,7 +26,7 @@ Standards on the whole are voluntary but can be formally recognised in regulatio Furthermore, they can be tools used as part of compliance towards governance and assurance frameworks. Standards can be in a variety of forms but commonly are established and disseminated as documents approved by a recognised body. -They provide common and repeatable rules, requirements, norms, guidelines and characteristics for activities that will lead to their associated outcomes; and are aimed at providing order in the contexts where they are applied. +They provide common and repeatable rules, requirements, norms, guidelines and characteristics for activities that will lead to their associated outcomes; and are aimed at providing order in the contexts where they are applied. ## Different types of standards @@ -34,7 +34,7 @@ Standards find application across diverse domains and sectors. They serve to encode technical specifications related to the measurement, design, or performance of products and systems. Additionally, standards extend their influence to evaluating the impacts or efficiency of broader processes or services. -While some standards are uncomplicated, offering clear metric definitions (e.g. the standardised format of A4 and related paper sizes adopted globally), others offer guidance on intricate, context-specific processes. +While some standards are uncomplicated, offering clear metric definitions (e.g. the standardised format of A4 and related paper sizes adopted globally), others offer guidance on intricate, context-specific processes. Below are some of the categories of standards available. @@ -67,7 +67,7 @@ These standards often form the baseline language utilised in other standards sup ### Process, management, and governance Process and management standards assist organisational processes and approaches to follow well defined steps to achieve their aims and objectives. -These standards are in-place to guide areas such as; quality assurance, risk management, management systems, benchmarking and regulatory compliance. +These standards are in-place to guide areas such as; quality assurance, risk management, management systems, benchmarking and regulatory compliance. diff --git a/site/docs/guidance/case-management.md b/site/docs/guidance/case-management.md new file mode 100644 index 00000000..1fb644f8 --- /dev/null +++ b/site/docs/guidance/case-management.md @@ -0,0 +1,31 @@ +# TEA Case Management + +## Using templates and patterns + +Importing templates and patterns can significantly accelerate the development of your assurance cases, providing a solid foundation built on industry best practices. Whether you're new to assurance case development or an experienced practitioner, these resources are designed to enhance the quality and efficacy of your ethical assurance efforts. + +This guide is designed to streamline your experience in leveraging pre-defined templates and patterns for creating and managing assurance cases. By importing templates and patterns, you can jumpstart the development of your assurance cases, ensuring you adhere to best practices and standards from the outset. + +Templates and patterns are foundational tools within the TEA platform, providing structured outlines that encapsulate best practices for assurance case development. These resources are invaluable for users seeking to ensure their technology projects meet ethical, legal, and social standards. + +Templates are pre-designed frameworks for assurance cases that outline the basic structure, including goals, claims, contexts, and evidence placeholders. + +Only one template is currently built into the platform: the "Minimal" template. This template contains a pre-organised view featuring a Goal, its Context, and a Claim. This setup serves as an intuitive starting point, guiding users through the initial phases of assurance case development with a clear, manageable structure. + +However, if you want to access other templates, you can consult the TEA repository where you will find more worked examples and templates that you can import via the Import File feature . + +### Using the Minimal template + +1. Navigate to the Dashboard (make sure you are logged in) +2. If you want to use the built-in template ("Minimal"), click the "Create a new case" button. In the dialog, fill in a Title and a Description, press "Continue". On the next page, select "Minimal" and press "Continue". +3. Your case should now be set up with the minimal template. + +### Using a template from the TEA repository + +1. Navigate to the and select a template. Click on the "Copy URL" button next to the template you want to use. +2. Navigate to the Dashboard (make sure you are logged in) +3. Press the "Import File" button. +4. Press the "Url upload" radio button. +5. Paste the URL you copied from the documentation here. (e.g. https://github.com/alan-turing-institute/AssurancePlatform/raw/adding-more-docs/worked-examples/tea-dh/json/5.1.json) +6. Press "Continue" +7. Your template should now have loaded in the Case Builder diff --git a/site/docs/guidance/exporting.md b/site/docs/guidance/exporting.md new file mode 100644 index 00000000..f8649065 --- /dev/null +++ b/site/docs/guidance/exporting.md @@ -0,0 +1,31 @@ +# Exporting TEA Cases + +Exporting your TEA cases is a straightforward process designed to facilitate the sharing and archiving of your assurance work. + +Exporting your assurance cases from the TEA platform allows you to share your work with stakeholders, archive your cases, or simply keep a local copy for your records. The platform supports exporting cases in two different formats. + +By following the simple steps in this guide, you can communicate your commitment to ethical technology development and assurance to all relevant stakeholders. + +## Step-by-step Guide + +### Step 1: Select Your Case +- Navigate to the dashboard of the TEA platform and locate the assurance case you wish to export. +- Open the assurance case to access the detailed view. + +### Step 2: Choose Export Option + +- Look for the “Export” button or in the case view. It is located in the menu that appears if you press the three dots that appear next to the title of your case. +- Click on “Export” to see the available format options. + +### Step 3: Select Format +- The TEA platform offers two formats for export and data interchange: JSON and SVG. Choose the format that best suits your needs. + +### Step 4: Download the File +- After selecting the format, initiate the export process. The platform will prepare the file for download. +- Once the file is ready, you may be prompted to confirm the download or it might start automatically. Ensure you save the file in your desired location. + +## Tips for Exporting Cases + +- Quickly **review your assurance case** for completeness and accuracy before exporting. Make any necessary updates to ensure the exported document accurately reflects your case. +- Consider **exporting your assurance cases periodically** to create backups and document the evolution of your assurance arguments over time. +- When sharing exported cases with stakeholders, **be mindful of sensitive information** and ensure your sharing method complies with data protection regulations. diff --git a/site/docs/guidance/sharing.md b/site/docs/guidance/sharing.md new file mode 100644 index 00000000..12bfd90b --- /dev/null +++ b/site/docs/guidance/sharing.md @@ -0,0 +1,58 @@ +# Sharing TEA Cases + +## File formats + +The TEA platform enhances collaboration and transparency by enabling users to share assurance cases in versatile formats. Understanding the available file formats for exporting and sharing TEA cases is crucial for effective collaboration. + +By leveraging the appropriate file format, you can maximize the impact and utility of your assurance cases, fostering better understanding, collaboration, and engagement among all stakeholders involved in the ethical assurance process. + +The platform supports two primary file formats for export: JSON and SVG. Each format serves distinct purposes, catering to different needs for data exchange, visualization, and re-importation into the TEA platform or other compatible systems. + +### Formats + +| Format | Purpose | Advantage | Use case | +|--------|---------|-----------|-----------| +JSON | The JSON (JavaScript Object Notation) format is designed for data exchange, allowing for the structured representation of the assurance case in a standard, machine-readable format. It is ideal for sharing cases with other systems that accept JSON data or for migrating cases between different deployments of the TEA platform.| JSON files are lightweight and easily parsed by many programming languages, making them suitable for automated processing, data analysis, and integration tasks. Exporting to JSON ensures that all elements of the assurance case, including goals, contexts, claims, and evidence, are preserved in detail. | Ideal for backing up cases, sharing with technical stakeholders, or integrating assurance case data into other software tools and platforms that support JSON. +SVG | The SVG (Scalable Vector Graphics) format provides a visual representation of the assurance case, suitable for presentations, reports, and stakeholder reviews. The SVG files include the data of the case built into the metadata, enabling the visualization to be re-imported into the TEA platform. | SVG files maintain high-quality visual fidelity at any scale, making them perfect for incorporating into documents or presentations that require graphical representation of the assurance case. The embedded case data ensures that the visual representation can be fully integrated back into the TEA platform for further editing or review. | Best suited for sharing the assurance case with non-technical stakeholders, displaying the case structure in documentation, or conducting reviews where a visual overview of the case is beneficial. + +### Tips for Sharing Cases + +When sharing TEA cases, consider the format that best matches the needs of your audience and the intended use: + +**Technical Integration**: Opt for JSON when the case needs to be processed, analyzed, or integrated with other systems. +**Visual Presentation**: Use SVG for stakeholder presentations, documentation, or any scenario where a graphical overview of the case adds value. + +Additionally, when sharing cases externally, **ensure that sensitive information is handled** in accordance with your organization's data protection policies and compliance requirements. + +## Sharing TEA Cases via GitHub + +GitHub, a popular platform for version control and collaboration, is recommended for sharing TEA cases due to its accessibility and ease of use. + +By sharing TEA cases via GitHub, you not only benefit from an efficient, collaborative platform but also contribute to the growing body of knowledge around ethical assurance in technology, making it more accessible and impactful. + +### Benefits of Using GitHub + +Hosting TEA cases on GitHub is not only easy. You can also leverage the platform's robust features for version control, issue tracking, and collaboration, making it an ideal choice for managing and sharing assurance cases with a broader community. + +**Version Control**: GitHub provides comprehensive version control features, ensuring changes to assurance cases are tracked, and previous versions are accessible. + +**Collaboration**: Invite collaborators to contribute, review, or provide feedback on assurance cases directly within GitHub, fostering a collaborative environment. + +**Accessibility**: Hosting your assurance case on a public GitHub repository makes it easily accessible to anyone interested, facilitating knowledge sharing within the TEA community and beyond. + +**Permanent Links**: GitHub offers permanent links to specific versions of files, ensuring that references to your assurance cases remain valid and accessible over time. + +### How to Share TEA Cases on GitHub + +1. **Export Your Case**: Begin by exporting your assurance case from the TEA platform in either JSON or SVG format, depending on your sharing needs. [LINK TO EXPORT SECTION] +2. **Create a GitHub Repository**: If you don't already have one, create a new repository on GitHub for hosting your TEA cases. Ensure the repository is set to public if you intend to share your case with the wider community. +3. **Upload the Case File**: Upload your exported TEA case file(s) to the GitHub repository. You can organize multiple cases within the same repository using folders. +4. **Share the Link**: Once uploaded, you can share the link to your repository or specific files within it. For JSON files intended for import into TEA, ensure the URL points directly to the raw version of the file. + +### Best Practices for Sharing on GitHub + +**Documentation**: Include a README file in your repository with information about the assurance cases, how to use them, and any relevant context or instructions for collaborators. [DOES TTW HAVE SOME INFO HERE?] + +**Licensing**: Consider adding a license file to your repository to clearly communicate how others can use or contribute to your assurance cases. [LINK TO TTW HERE] + +**Engage with the Community**: Use issues and pull requests to engage with users who may have questions, suggestions, or contributions to your assurance cases. From 708bab948dd7d6f306d91bcaf297ee2f52673ac3 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:12:05 +0000 Subject: [PATCH 09/35] Fixing up some markdown --- site/docs/guidance/case-builder.md | 2 +- site/docs/guidance/exporting.md | 3 +++ site/docs/guidance/getting-started.md | 37 +++++++++++++++++++++++++++ site/docs/guidance/sharing.md | 6 ++--- 4 files changed, 44 insertions(+), 4 deletions(-) create mode 100644 site/docs/guidance/getting-started.md diff --git a/site/docs/guidance/case-builder.md b/site/docs/guidance/case-builder.md index e646730f..3825adbe 100644 --- a/site/docs/guidance/case-builder.md +++ b/site/docs/guidance/case-builder.md @@ -34,7 +34,7 @@ Claims are specific assertions that support your goal within its context. 2. **Add a Claim**. Click on "Add Claim" and provide a concise statement that you plan to justify through evidence. For example, "The system encrypts all user data." -3. **Detail Your Claim**. You may also add a longer description ==pending update to the 60 characters limitation== if necessary. Again, your claim will be saved automatically. +3. **Detail Your Claim**. You may also add a longer description if necessary. Again, your claim will be saved automatically. ### Adding Evidence diff --git a/site/docs/guidance/exporting.md b/site/docs/guidance/exporting.md index f8649065..bb53862d 100644 --- a/site/docs/guidance/exporting.md +++ b/site/docs/guidance/exporting.md @@ -9,6 +9,7 @@ By following the simple steps in this guide, you can communicate your commitment ## Step-by-step Guide ### Step 1: Select Your Case + - Navigate to the dashboard of the TEA platform and locate the assurance case you wish to export. - Open the assurance case to access the detailed view. @@ -18,9 +19,11 @@ By following the simple steps in this guide, you can communicate your commitment - Click on “Export” to see the available format options. ### Step 3: Select Format + - The TEA platform offers two formats for export and data interchange: JSON and SVG. Choose the format that best suits your needs. ### Step 4: Download the File + - After selecting the format, initiate the export process. The platform will prepare the file for download. - Once the file is ready, you may be prompted to confirm the download or it might start automatically. Ensure you save the file in your desired location. diff --git a/site/docs/guidance/getting-started.md b/site/docs/guidance/getting-started.md new file mode 100644 index 00000000..933b5ea3 --- /dev/null +++ b/site/docs/guidance/getting-started.md @@ -0,0 +1,37 @@ +--- +status: draft +tags: + - Introductory Resource +--- + +# Quickly Getting Started with the TEA Platform + +Getting started with the Trustworthy and Ethical Assurance (TEA) Platform is a straightforward process designed to get you up and running with creating, managing, and sharing assurance cases in no time. Follow these simple steps to begin your journey towards more transparent and ethical technology assurance. + +## Step 1: Sign Up or Log In + +Visit the TEA Platform's homepage and locate the "Sign Up" or "Log In" buttons. If you're a new user, you'll need to register for an account using the "Sign Up" feature. Existing users can enter their credentials to log in. + + + +## Step 2: Familiarise Yourself with the Dashboard + +Once logged in, you'll be greeted by the dashboard. This is your central hub for accessing all features of the TEA Platform, including creating new assurance cases, viewing existing ones, and accessing educational resources. + +## Step 3: Creating a New Assurance Case + +To create a new assurance case, click on the "Create a new case" button from the dashboard. You'll be prompted to enter details such as the case name and description. Fill out the necessary fields and submit to create your case. + + + +## Step 4: Building Your Assurance Case + +With your assurance case created, it's time to start adding elements like Goals, Contexts, and Evidence. The TEA Platform's intuitive interface allows you to build your assurance case visually. + + + +## Step 4: Exporting and Publishing Your Work + +Once you're satisfied with your assurance case, you can export it in various formats for external review or publication. The platform supports exporting to formats like JSON for data exchange or SVG for visual representation. + + diff --git a/site/docs/guidance/sharing.md b/site/docs/guidance/sharing.md index 12bfd90b..2202e7ac 100644 --- a/site/docs/guidance/sharing.md +++ b/site/docs/guidance/sharing.md @@ -44,15 +44,15 @@ Hosting TEA cases on GitHub is not only easy. You can also leverage the platform ### How to Share TEA Cases on GitHub -1. **Export Your Case**: Begin by exporting your assurance case from the TEA platform in either JSON or SVG format, depending on your sharing needs. [LINK TO EXPORT SECTION] +1. **Export Your Case**: Begin by exporting your assurance case from the TEA platform in either JSON or SVG format, depending on your sharing needs. 2. **Create a GitHub Repository**: If you don't already have one, create a new repository on GitHub for hosting your TEA cases. Ensure the repository is set to public if you intend to share your case with the wider community. 3. **Upload the Case File**: Upload your exported TEA case file(s) to the GitHub repository. You can organize multiple cases within the same repository using folders. 4. **Share the Link**: Once uploaded, you can share the link to your repository or specific files within it. For JSON files intended for import into TEA, ensure the URL points directly to the raw version of the file. ### Best Practices for Sharing on GitHub -**Documentation**: Include a README file in your repository with information about the assurance cases, how to use them, and any relevant context or instructions for collaborators. [DOES TTW HAVE SOME INFO HERE?] +**Documentation**: Include a README file in your repository with information about the assurance cases, how to use them, and any relevant context or instructions for collaborators. -**Licensing**: Consider adding a license file to your repository to clearly communicate how others can use or contribute to your assurance cases. [LINK TO TTW HERE] +**Licensing**: Consider adding a license file to your repository to clearly communicate how others can use or contribute to your assurance cases. **Engage with the Community**: Use issues and pull requests to engage with users who may have questions, suggestions, or contributions to your assurance cases. From cdc781e8e1be386c6d7fd148abfa989b89e4948f Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:17:47 +0000 Subject: [PATCH 10/35] Fixing up some further markdown --- site/docs/guidance/case-builder.md | 7 ++++++- site/docs/guidance/case-management.md | 9 +++++++-- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/site/docs/guidance/case-builder.md b/site/docs/guidance/case-builder.md index 3825adbe..324e0afa 100644 --- a/site/docs/guidance/case-builder.md +++ b/site/docs/guidance/case-builder.md @@ -1,4 +1,9 @@ -# TEA Case Builder +--- +tags: + - core elements +--- + +# An Introduction to the TEA Case Builder The Trustworthy and Ethical Assurance Platform is dedicated to simplifying the process of creating, managing, and sharing assurance cases. Our Assurance Case Builder is a core feature of the platform, designed to help you visually and logically structure your assurance cases with ease. diff --git a/site/docs/guidance/case-management.md b/site/docs/guidance/case-management.md index 1fb644f8..acf6c4c3 100644 --- a/site/docs/guidance/case-management.md +++ b/site/docs/guidance/case-management.md @@ -1,4 +1,9 @@ -# TEA Case Management +--- +tags: + - core elements +--- + +# Managing TEA Assurance Cases ## Using templates and patterns @@ -25,7 +30,7 @@ However, if you want to access other templates, you can consult the TEA reposito 1. Navigate to the and select a template. Click on the "Copy URL" button next to the template you want to use. 2. Navigate to the Dashboard (make sure you are logged in) 3. Press the "Import File" button. -4. Press the "Url upload" radio button. +4. Press the "URL upload" radio button. 5. Paste the URL you copied from the documentation here. (e.g. https://github.com/alan-turing-institute/AssurancePlatform/raw/adding-more-docs/worked-examples/tea-dh/json/5.1.json) 6. Press "Continue" 7. Your template should now have loaded in the Case Builder From 956314d9d6bbbdb35f5a5809da4e5993f9fe92b7 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:17:53 +0000 Subject: [PATCH 11/35] Linking with Guidance index --- site/docs/guidance/index.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/site/docs/guidance/index.md b/site/docs/guidance/index.md index 64315b87..63c12630 100644 --- a/site/docs/guidance/index.md +++ b/site/docs/guidance/index.md @@ -1,7 +1,5 @@ --- status: draft -tags: - - Introductory Resource --- !!! warning "Draft" @@ -11,9 +9,10 @@ tags: In this section you will find the main documentation and user guidance for the TEA platform. For those who are completely new to the platform, we recommend you follow these guides in order : -1. Getting started with the TEA platform (*in progress*) -2. Building an assurance case (*in progress*) +1. [Quickly Getting Started with the TEA Platform](getting-started.md) (*in progress*) +2. [An Introduction to the TEA Case Builder](case-builder.md) (*in progress*) 3. [Components of an assurance case](components.md) -4. Managing and sharing assurance cases (*in progress*) +4. [Managing TEA Assurance Cases](case-management.md) (*in progress*) +5. [Exporting TEA Cases](exporting.md) (*in progress*) You can also find more advanced documentation (e.g. deployment instructions, API documentation) in our [platform details](../platform-details/about.md) section. From b75cafd01ed5d58a6bb31a289092ad2a29f24517 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:18:05 +0000 Subject: [PATCH 12/35] Linking with mkdocs menu --- site/mkdocs.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/site/mkdocs.yml b/site/mkdocs.yml index dc6ffe05..3e560095 100644 --- a/site/mkdocs.yml +++ b/site/mkdocs.yml @@ -133,7 +133,11 @@ nav: - Open Challenges in Trustworthy and Ethical Assurance: introductory-resources/open-challenges.md - User Guidance: - About this Section: guidance/index.md + - Quickly Getting Started with the TEA Platform: guidance/getting-started.md + - An Introduction to the TEA Case Builder: guidance/case-builder.md - Components of an Assurance Case: guidance/components.md + - Managing TEA Assurance Cases: guidance/case-management.md + - Exporting TEA Cases: guidance/exporting.md # - Operationalising Ethical Principles: guidance/operationalising-ethics.md # - TEA and the Project Lifecycle: guidance/tea-project-lifecycle.md # - The Role of Standards in TEA: guidance/standards.md From 7f5427e613c1536f90e1b73caac9f6ef9b04aef4 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:23:55 +0000 Subject: [PATCH 13/35] Adding placeholder for "Standards and their role in assurance" --- site/mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/site/mkdocs.yml b/site/mkdocs.yml index 3e560095..fde84d3f 100644 --- a/site/mkdocs.yml +++ b/site/mkdocs.yml @@ -131,6 +131,7 @@ nav: - The Assurance Ecosystem: introductory-resources/assurance-ecosystem.md - An Introduction to Argument-Based Assurance: introductory-resources/argument-based-assurance.md - Open Challenges in Trustworthy and Ethical Assurance: introductory-resources/open-challenges.md + # - Standards and their role in assurance: introductory-resources/standards.md - User Guidance: - About this Section: guidance/index.md - Quickly Getting Started with the TEA Platform: guidance/getting-started.md From 22f92193392dd73785ef31bfa4f07976eae6c0d6 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:24:03 +0000 Subject: [PATCH 14/35] Correct link --- site/docs/introductory-resources/standards.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/introductory-resources/standards.md b/site/docs/introductory-resources/standards.md index 41036838..7af4bfe0 100644 --- a/site/docs/introductory-resources/standards.md +++ b/site/docs/introductory-resources/standards.md @@ -201,7 +201,7 @@ Find an instance of a standard to use as an example. Similar to how CDEI present ### Evidential grounding and justification of property claims Property claims require evidential grounding. -That is, the validity of a claim needs to be justified by connecting the claim to evidence through a `supported by` link (see [guidance](../guidance/components/#support-links)). +That is, the validity of a claim needs to be justified by connecting the claim to evidence through a `supported by` link (see [guidance](../guidance/components.md#support-links)). But how does a project team or organisation know which evidence to select, and whether it is sufficient to justify the claims being made? This is where standards can provide useful support? For instance, `measurement and test methods` and `product and performance requirements` standards are crucial for determining whether a system meets the required performance levels. From 9221df9425e629ca7bcfa76760171dbe49e15bb8 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:24:46 +0000 Subject: [PATCH 15/35] Adding in link to "Sharing TEA Cases" --- site/docs/guidance/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/site/docs/guidance/index.md b/site/docs/guidance/index.md index 63c12630..25d1bd35 100644 --- a/site/docs/guidance/index.md +++ b/site/docs/guidance/index.md @@ -14,5 +14,6 @@ For those who are completely new to the platform, we recommend you follow these 3. [Components of an assurance case](components.md) 4. [Managing TEA Assurance Cases](case-management.md) (*in progress*) 5. [Exporting TEA Cases](exporting.md) (*in progress*) +6. [Sharing TEA Cases](sharing.md) (*in progress*) You can also find more advanced documentation (e.g. deployment instructions, API documentation) in our [platform details](../platform-details/about.md) section. From 2dd00a48db45c6aa2290ba7b414243a8271ede29 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:31:01 +0000 Subject: [PATCH 16/35] Adding in a TODO --- site/docs/guidance/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/guidance/index.md b/site/docs/guidance/index.md index 25d1bd35..59a91a2a 100644 --- a/site/docs/guidance/index.md +++ b/site/docs/guidance/index.md @@ -7,7 +7,7 @@ status: draft This section is being drafted. In this section you will find the main documentation and user guidance for the TEA platform. -For those who are completely new to the platform, we recommend you follow these guides in order : +For those who are completely new to the platform, we recommend you follow these guides in order : 1. [Quickly Getting Started with the TEA Platform](getting-started.md) (*in progress*) 2. [An Introduction to the TEA Case Builder](case-builder.md) (*in progress*) From 227b95047288e99a61c339029150119c9849f135 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:33:31 +0000 Subject: [PATCH 17/35] Adding in landing page for CoP --- site/docs/community/index.md | 42 +++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/site/docs/community/index.md b/site/docs/community/index.md index f7159817..945ba215 100644 --- a/site/docs/community/index.md +++ b/site/docs/community/index.md @@ -1,3 +1,43 @@ # Community of Practice - +Welcome to the Community page of the Trustworthy and Ethical Assurance (TEA) Platform documentation. At the heart of the TEA Platform is a commitment to fostering a vibrant and engaged community of practice. We believe that the challenges of ethical assurance in data-driven technologies are best addressed collaboratively, bringing together diverse perspectives and expertise. Building a community around the platform not only enriches the user experience but also strengthens the integrity and impact of the assurance cases developed through it. + +## Building Our Community Infrastructure + +We are currently in the process of building out our community infrastructure for the TEA Platform. This includes developing forums, collaborative tools, and resources to support our members in their assurance case work. Our goal is to create a dynamic and supportive environment that facilitates meaningful interactions and collaborations within the community. + +!!! example "Join us in shaping the future of ethical assurance" + + We are excited about the potential of the TEA Platform to bring together a community of practitioners passionate about ethical technology governance. If you are interested in talking further about our community development efforts or wish to contribute, please reach out to the Research Application Manager, Kalle Westerling, at kwesterling@turing.ac.uk. We welcome your insights, expertise, and enthusiasm as we work together to build a community that reflects our shared values and goals. + +Together, we can build a community that not only advances the field of technology assurance but also ensures that the development and application of data-driven technologies are conducted ethically, transparently, and inclusively. + +## Our Commitment to Community Values + +The TEA Platform is guided by core values that shape our approach to developing a community of practice: + + + + + + + + + + + + + + +
+ 👐 Inclusivity: We are committed to making the assurance process accessible to a diverse set of stakeholders, ensuring that technology governance is a collaborative and inclusive endeavor. + + 📖 Transparency: We believe in open communication and clear documentation of assurance cases, enabling stakeholders to understand and trust the ethical foundations of technology projects. +
+ 💡 Innovation: We are dedicated to continuously pushing the boundaries of what is possible in ethical assurance, developing creative solutions that address the evolving challenges of data-driven technologies. + + 🤝 Collaboration: We encourage the sharing of knowledge, resources, and best practices, promoting collaborative advancement in the field of technology assurance by fostering a supportive community infrastructure. +
+ 🛡️ Integrity: We are committed to upholding high standards of honesty and accountability in all our endeavours, aiming that the technologies we help assure are developed with societal benefit in mind. + +
From 88ae1216afeaf9ed95a886e6694235e31fc001b2 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:33:59 +0000 Subject: [PATCH 18/35] Commenting out values --- site/docs/community/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/site/docs/community/index.md b/site/docs/community/index.md index 945ba215..80e2e4d2 100644 --- a/site/docs/community/index.md +++ b/site/docs/community/index.md @@ -12,6 +12,9 @@ We are currently in the process of building out our community infrastructure for Together, we can build a community that not only advances the field of technology assurance but also ensures that the development and application of data-driven technologies are conducted ethically, transparently, and inclusively. + From 225a9cfe8ab2478694f0ba6e7200b39b5cb304c2 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:42:59 +0000 Subject: [PATCH 19/35] Changing font to stay on brand --- site/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/mkdocs.yml b/site/mkdocs.yml index fde84d3f..60a7786e 100644 --- a/site/mkdocs.yml +++ b/site/mkdocs.yml @@ -47,7 +47,7 @@ theme: scheme: default font: - text: Roboto + text: Plus Jakarta Sans code: Roboto Mono # favicon: assets/logo.png icon: From 276a4877f46788778f729d69660147ec102cc835 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:43:14 +0000 Subject: [PATCH 20/35] Removing as we're not asking for GitHub access currently --- site/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/mkdocs.yml b/site/mkdocs.yml index 60a7786e..e06a9451 100644 --- a/site/mkdocs.yml +++ b/site/mkdocs.yml @@ -152,5 +152,5 @@ nav: - Resetting the Database: platform-details/resetting-database.md - Community of Practice: - Community of Practice: community/index.md - - Why We Ask for Access to Your GitHub: community/github-access.md + # - Why We Ask for Access to Your GitHub: community/github-access.md - Upcoming community events: blog/index.md From 7150e270740ee6ec4720c6ab6e88c6b8aa2ff618 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:44:33 +0000 Subject: [PATCH 21/35] Connecting up Community Support page --- site/mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/site/mkdocs.yml b/site/mkdocs.yml index e06a9451..6ac5dd5f 100644 --- a/site/mkdocs.yml +++ b/site/mkdocs.yml @@ -152,5 +152,6 @@ nav: - Resetting the Database: platform-details/resetting-database.md - Community of Practice: - Community of Practice: community/index.md + - Community Support: community/community-support.md # - Why We Ask for Access to Your GitHub: community/github-access.md - Upcoming community events: blog/index.md From 5001ddf2a67e3b281142109eeafedb629fe03c77 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:47:56 +0000 Subject: [PATCH 22/35] Editing Community Support --- site/docs/community/community-support.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/site/docs/community/community-support.md b/site/docs/community/community-support.md index f0f9e46d..eaeae5c4 100644 --- a/site/docs/community/community-support.md +++ b/site/docs/community/community-support.md @@ -12,7 +12,7 @@ This section guides you on how to use GitHub issues effectively to share your TE ### Creating a GitHub Issue for Sharing a TEA Case -1. **Navigate to Your Repository**: Open the GitHub repository where your TEA case is hosted. [LINK TO SHARE TEA CASES ON GITHUB] +1. **Navigate to Your Repository**: Open the GitHub repository where your TEA case is hosted. 2. **Open the Issues Tab**: Click on the "Issues" tab near the top of the repository page. 3. Click the **"New issue"** button to start drafting your issue. Give your issue a clear title that indicates it’s about sharing a TEA case for feedback. In the description, provide context about the assurance case, including its goals, the specific areas where you're seeking feedback, and any particular challenges you're facing. 4. Include a **direct link to the assurance case file** (preferably the raw file link if it’s in JSON format for easy import) or to the folder containing the case if there are multiple related files. @@ -42,22 +42,22 @@ Below, we discuss how you can actively participate in discussions, report issues ### Engaging in Discussions -The repository's Issues [LINK] section is an excellent place for initiating discussions on a wide range of topics, including feature requests, bug reports, and general queries about the TEA platform. This section is where you can voice your thoughts and contribute to ongoing conversations, whether you've encountered a technical glitch, have an idea for a new feature that could improve the platform, or simply have a question about how something works. +The [repository's Issues](https://www.github.com/alan-turing-institute/AssurancePlatform/issues) section is an excellent place for initiating discussions on a wide range of topics, including feature requests, bug reports, and general queries about the TEA platform. This section is where you can voice your thoughts and contribute to ongoing conversations, whether you've encountered a technical glitch, have an idea for a new feature that could improve the platform, or simply have a question about how something works. ### Reporting Bugs -If you encounter a problem or an error while using the TEA platform, we encourage you to report it via the repository's Issues section. When reporting a bug, please provide a detailed description of the issue, steps to reproduce the problem, and any relevant screenshots or error messages. This information is invaluable in diagnosing and resolving issues more efficiently. +If you encounter a problem or an error while using the TEA platform, we encourage you to report it via the [repository's Issues](https://www.github.com/alan-turing-institute/AssurancePlatform/issues) section. When reporting a bug, please provide a detailed description of the issue, steps to reproduce the problem, and any relevant screenshots or error messages. This information is invaluable in diagnosing and resolving issues more efficiently. ### Requesting Features -The TEA platform is continually being developed, and user feedback is a crucial driver of this process. If you have an idea for a new feature or an enhancement to an existing one, please share it as a feature request in the Issues section. Describe your proposed feature, its potential benefits, and how it could be implemented within the platform. Community feedback on these proposals can help prioritize development efforts. +The TEA platform is continually being developed, and user feedback is a crucial driver of this process. If you have an idea for a new feature or an enhancement to an existing one, please share it as a feature request in the Issues section. Describe your proposed feature, its potential benefits, and how it could be implemented within the platform. Community feedback on these proposals can help prioritize development efforts. ### Contributing to the Codebase -For users with programming experience interested in contributing to the TEA platform, the repository contains detailed instructions on how to contribute to the codebase. Whether it's developing new features, fixing bugs, or improving documentation, your contributions are welcome. Here's how you can get started: +For users with programming experience interested in contributing to the TEA platform, the [repository](https://www.github.com/alan-turing-institute/AssurancePlatform/issues) contains detailed instructions on how to contribute to the codebase. Whether it's developing new features, fixing bugs, or improving documentation, your contributions are welcome. Here's how you can get started: -**Read the Contribution Guidelines**: Before making any contributions, please review the contribution guidelines provided in the repository. These guidelines cover the process for submitting pull requests, coding standards, and other important practices. +**Read the Contribution Guidelines**: Before making any contributions, please review [repository's Issues](https://github.com/alan-turing-institute/AssurancePlatform/blob/main/CONTRIBUTING.md). These guidelines cover the process for submitting pull requests, coding standards, and other important practices. -**Set Up Your Development Environment**: The documentation includes instructions for setting up your development environment, allowing you to work on the codebase, test changes, and ensure your contributions align with the platform's overall architecture and design principles. +**Set Up Your Development Environment**: The documentation includes [instructions for setting up your development environment](../platform-details/installation.md), allowing you to work on the codebase, test changes, and ensure your contributions align with the platform's overall architecture and design principles. **Submit a Pull Request**: Once you've made your changes, submit a pull request through GitHub. Your pull request will be reviewed by the platform's maintainers, and feedback or requests for revisions will be communicated through the GitHub interface. From 66a6f2349a6084c50faa2de1ad26da6cc7554874 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:54:10 +0000 Subject: [PATCH 23/35] Moving link --- site/docs/community/community-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/community/community-support.md b/site/docs/community/community-support.md index eaeae5c4..c9c54f63 100644 --- a/site/docs/community/community-support.md +++ b/site/docs/community/community-support.md @@ -32,7 +32,7 @@ This section guides you on how to use GitHub issues effectively to share your TE ## TEA Platform Repository Discussions and Issues -The TEA (Trustworthy and Ethical Assurance) platform's repository on GitHub (https://github.com/alan-turing-institute/AssurancePlatform) serves as a central hub for community engagement, feature development, and issue tracking. +The TEA (Trustworthy and Ethical Assurance) platform's [repository on GitHub](https://github.com/alan-turing-institute/AssurancePlatform) serves as a central hub for community engagement, feature development, and issue tracking. It is our aim to make it a vibrant community space where users, developers, and stakeholders can collaborate to enhance the platform's functionality and usability. We want you all to come together to make the platform better for everyone. By engaging in discussions, reporting issues, requesting features, and contributing to the codebase, you play a vital role in the continuous improvement and success of the TEA platform. From 56a026db86baacdc03712b60c7adf8d882fa12ce Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:56:04 +0000 Subject: [PATCH 24/35] Choosing code font that's more aligned --- site/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/mkdocs.yml b/site/mkdocs.yml index 6ac5dd5f..aa789e3a 100644 --- a/site/mkdocs.yml +++ b/site/mkdocs.yml @@ -48,7 +48,7 @@ theme: font: text: Plus Jakarta Sans - code: Roboto Mono + code: Source Code Pro # favicon: assets/logo.png icon: logo: material/vector-circle From 514b7f932c293f320502b0e44baed29fcf3f848a Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 7 Feb 2024 17:59:42 +0000 Subject: [PATCH 25/35] Adding In Progress status to "The Role of Standards" --- site/docs/module_tracker.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/module_tracker.csv b/site/docs/module_tracker.csv index 2f740814..286ce293 100644 --- a/site/docs/module_tracker.csv +++ b/site/docs/module_tracker.csv @@ -4,5 +4,5 @@ The Assurance Ecosystem—A Brief Overview,"An overview of the assurance ecosyst An Introduction to Argument-Based Assurance,"A simple introduction to argument-based assurance, including its history and motivation.",Introductory Resource,Planning, Operationalising Ethical Principles—Putting TEA into Practice,How to operationalise ethical principles,User Guidance,Planning, TEA and the Project Lifecycle,How to embed trustworthy and ethical assurance over the course of a project's lifecycle,User Guidance,Planning, -The Role of Standards,An introduction to standards as they apply to trustworthy and ethical assurance,User Guidance,Planning, +The Role of Standards,An introduction to standards as they apply to trustworthy and ethical assurance,User Guidance,In Progress, Open Challenges in Assurance,"An overview of open challenges and research questions, inlcuding links to further resources",User Guidance,Planning, From 3cf77afd1049a4c841c12ba9258d7a7a9d603081 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Thu, 8 Feb 2024 15:32:06 +0000 Subject: [PATCH 26/35] Remove misplaced markdown files --- HOWTO_reset_the_database.md | 49 ------------------------------------- 1 file changed, 49 deletions(-) delete mode 100644 HOWTO_reset_the_database.md diff --git a/HOWTO_reset_the_database.md b/HOWTO_reset_the_database.md deleted file mode 100644 index 76e6ed43..00000000 --- a/HOWTO_reset_the_database.md +++ /dev/null @@ -1,49 +0,0 @@ -There are a couple of reasons why one might wish to remove the contents of the -AssurancePlatform database and recreate a fresh one: - -- After a workshop or demo session, may want to remove all users and created - cases. -- You (or someone) has made some non-migratable schema changes in the code. How - to do this depends on whether you are running locally, or on a - cloud-deployment (such as having followed the instructions for deploying on - Azure [here](HOWTO_deploy_to_Azure.md)). - -## Running on your local machine - -Unless you have changed some settings, you will likely be using a local `sqlite` -file for your database. To remove it, simply remove the file -`eap_backend/db.sqlite3`. Then run (having setup the environment for the backend -following the instructions [here](README.md)) the commands: - -``` -python manage.py makemigrations && python manage.py migrate -``` - -and next time you run the backend, you should have a new sqlite file with an -empty database. - -## Running on Azure - -To delete and recreate the database on an Azure deployment, it is necessary to -connect to it using something like `psql` (as described -[here](HOWTO_deploy_to_Azure.md)). - -1. If you haven't already done this when setting up, ensure that your IP address - can connect to the database server. Via the Azure portal, find your database - resource, and click on "Connection security" in the left sidebar, click "Add - current client IP address", and save. -2. If you don't already have it, install `psql`. For Mac/Homebrew, - `brew install postgresql` should work. For other OSs, Google is available :) -3. drop and recreate the database via psql. - -```psql --host=SERVER_NAME.postgres.database.azure.com --port=5432 --username=ADMIN_USERNAME@SERVER_NAME --dbname=postgres -postgres=> DROP DATABASE eap; -postgres=> CREATE DATABASE eap; -postgres=> \c eap; -postgres=> \q -``` - -where `SERVER_NAME`, `ADMIN_USERNAME`, and the admin password should all be -available via the Azure portal (password may be stored in a keyvault). 4. In the -Azure portal, find the Web app for the backend, and restart it. After a few -minutes, everything should be back up and running. From 44d0a7c6384009dc263b91016f1ce58c1e7e0912 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Thu, 8 Feb 2024 15:44:35 +0000 Subject: [PATCH 27/35] Adding in note about missing document --- site/docs/guidance/components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/guidance/components.md b/site/docs/guidance/components.md index 2bd43568..a18f1477 100644 --- a/site/docs/guidance/components.md +++ b/site/docs/guidance/components.md @@ -113,7 +113,7 @@ following example. consistency with this standard, which is why property claims have the same type as goal claims, but adds an additional descriptive layer to better represent the ethical process of deliberation and reflection (see section on - [Operationalising Principles](operationalising-principles.md)) + [Operationalising Principles](operationalising-principles.md)) [^modularity]: See earlier note about 'Multiple Goals and Modular Arguments'. From d363d564d70f92a20a7e212f582e76d1f6781c04 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Thu, 8 Feb 2024 16:00:48 +0000 Subject: [PATCH 28/35] Adding include-markdown plugin --- site/mkdocs.yml | 41 +++++++++++++++++++++++++++++++++++------ site/requirements.txt | 1 + 2 files changed, 36 insertions(+), 6 deletions(-) diff --git a/site/mkdocs.yml b/site/mkdocs.yml index aa789e3a..1704f1b0 100644 --- a/site/mkdocs.yml +++ b/site/mkdocs.yml @@ -66,6 +66,16 @@ plugins: authors: true draft: false - table-reader + - include-markdown: + encoding: ascii + preserve_includer_indent: false + dedent: false + trailing_newlines: true + comments: true + rewrite_relative_urls: true + heading_offset: 0 + start: + end: # Customization @@ -139,19 +149,38 @@ nav: - Components of an Assurance Case: guidance/components.md - Managing TEA Assurance Cases: guidance/case-management.md - Exporting TEA Cases: guidance/exporting.md + - Sharing TEA Cases: guidance/sharing.md # - Operationalising Ethical Principles: guidance/operationalising-ethics.md # - TEA and the Project Lifecycle: guidance/tea-project-lifecycle.md # - The Role of Standards in TEA: guidance/standards.md # - A Case Study: guidance/case-study.md - Platform Details: - About: platform-details/about.md - - Installation Instructions: platform-details/installation.md - - API Documentation: platform-details/api.md - - Azure Deployment: platform-details/azure.md - - GitHub OAuth: platform-details/github.md - - Resetting the Database: platform-details/resetting-database.md + - Docker Installation Guide: platform-details/docker-installation.md + - Backend: + - Backend Documentation for the TEA Platform: platform-details/backend/index.md + - Installation and Setup: platform-details/backend/installation.md + - Django Settings: platform-details/backend/django-settings.md + - Backend Management files: platform-details/backend/backend-management-files.md + - API Documentation: platform-details/backend/api/index.md + - Frontend: + - Frontend Documentation for the TEA Platform: platform-details/frontend/index.md + - Installation and Setup: platform-details/frontend/installation.md + - Frontend Configuration: platform-details/frontend/react-configuration.md + - React Components: platform-details/frontend/react-components.md + - Visualizing Assurance Cases with Mermaid.js: platform-details/frontend/mermaid.md + - Deployment: + - Deploying the TEA Platform on Microsoft Azure Cloud: platform-details/deployment/azure.md + # - GitHub OAuth: platform-details/github.md # TODO: No GitHub access currently + - Resetting the Database: + - Resetting the Database: platform-details/reset-database/index.md + - Resetting the Database on Azure Deployments: platform-details/reset-database/azure.md + - Resetting the Database on Local Deployments: platform-details/reset-database/local.md - Community of Practice: - Community of Practice: community/index.md - Community Support: community/community-support.md - # - Why We Ask for Access to Your GitHub: community/github-access.md + # - Why We Ask for Access to Your GitHub: community/github-access.md # TODO: No GitHub access currently - Upcoming community events: blog/index.md + +not_in_nav: | + _prerequisites.md diff --git a/site/requirements.txt b/site/requirements.txt index b90fdcf4..bc5f36ec 100644 --- a/site/requirements.txt +++ b/site/requirements.txt @@ -3,5 +3,6 @@ mkdocs-glightbox>=0.2.0 mkdocs-material>=9.1.14 mkdocs-rss-plugin>=1.8.0 mkdocs-table-reader-plugin>=2.0.1 +mkdocs-include-markdown-plugin>=6.0.4 # Requirements for additional plugins pillow>=9.2.0 From 19747ef7ed0ed7a47e2fe5cf6a9c6c59c4cc5152 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 8 Feb 2024 16:01:47 +0000 Subject: [PATCH 29/35] style: pre-commit fixes --- site/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/requirements.txt b/site/requirements.txt index bc5f36ec..8c419f39 100644 --- a/site/requirements.txt +++ b/site/requirements.txt @@ -1,8 +1,8 @@ CairoSVG>=2.5.2 mkdocs-glightbox>=0.2.0 +mkdocs-include-markdown-plugin>=6.0.4 mkdocs-material>=9.1.14 mkdocs-rss-plugin>=1.8.0 mkdocs-table-reader-plugin>=2.0.1 -mkdocs-include-markdown-plugin>=6.0.4 # Requirements for additional plugins pillow>=9.2.0 From 7c1fcff6fc755254846cd4ea3a56e9a966234c94 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Thu, 8 Feb 2024 17:49:28 +0000 Subject: [PATCH 30/35] Adding documentation strings to the React components --- .../src/components/CaseAccessibilityModal.jsx | 17 ++ frontend/src/components/CaseContainer.js | 36 +++- frontend/src/components/CaseCreator.js | 12 ++ frontend/src/components/CaseCreatorFlow.jsx | 15 +- frontend/src/components/CaseImporterFlow.jsx | 47 ++++- frontend/src/components/CaseMediaPreview.jsx | 19 ++ .../src/components/CasePermissionsManager.js | 21 +++ frontend/src/components/CaseTopBar.jsx | 26 +++ frontend/src/components/CommentSection.js | 39 ++++ frontend/src/components/CreateGroup.js | 9 + frontend/src/components/DeleteCaseModal.jsx | 18 ++ frontend/src/components/DeleteItemModal.jsx | 20 ++ frontend/src/components/ExportCaseModal.jsx | 19 ++ frontend/src/components/Home.js | 20 ++ frontend/src/components/ItemEditor.js | 117 +++++++++++- frontend/src/components/Login.js | 5 + frontend/src/components/Logout.js | 11 ++ frontend/src/components/ManageCases.jsx | 49 ++++- frontend/src/components/Mermaid.js | 50 ++++- frontend/src/components/Navigation.js | 25 +++ frontend/src/components/ParentSelector.js | 33 +++- frontend/src/components/PermissionSelector.js | 9 + frontend/src/components/Routes.js | 5 + frontend/src/components/SVGDownloader.js | 10 + frontend/src/components/Signup.js | 28 +++ frontend/src/components/TemplateSelector.js | 32 ++++ frontend/src/components/caseApi.js | 84 ++++++++- frontend/src/components/utils.js | 173 +++++++++++++++--- frontend/src/hooks/useAuth.js | 27 ++- 29 files changed, 912 insertions(+), 64 deletions(-) diff --git a/frontend/src/components/CaseAccessibilityModal.jsx b/frontend/src/components/CaseAccessibilityModal.jsx index eebb50a1..39a87ada 100644 --- a/frontend/src/components/CaseAccessibilityModal.jsx +++ b/frontend/src/components/CaseAccessibilityModal.jsx @@ -18,6 +18,23 @@ import configData from "../config.json"; import { Wheelchair } from "./common/Icons.jsx"; import ErrorMessage from "./common/ErrorMessage.jsx"; +/** + * CaseAccessibilityModal provides a modal dialog for editing the accessibility options, + * specifically the colour profile, of an assurance case diagram. Users can select from + * predefined colour schemes configured in `config.json` to enhance diagram accessibility. + * + * @param {Object} props The component props. + * @param {boolean} props.isOpen Indicates if the modal is open. + * @param {Function} props.onClose Function to call when closing the modal. + * @param {Function} props.onSuccess Function to call upon successful update of the case. + * @param {string} props.caseId The ID of the case being edited. + * @param {string} props.currentColour The current colour profile of the case diagram. + * + * This component utilizes the `editCase` API to submit the selected colour profile update, + * handling loading states, success, and error feedback within the modal dialog. The colour + * selection is made through a radio button group, offering a user-friendly way to enhance + * diagram accessibility for users with visual impairments. + */ function CaseAccessibilityModal({ isOpen, onClose, diff --git a/frontend/src/components/CaseContainer.js b/frontend/src/components/CaseContainer.js index 2f15efe6..25c5e602 100644 --- a/frontend/src/components/CaseContainer.js +++ b/frontend/src/components/CaseContainer.js @@ -15,6 +15,14 @@ import { ColumnFlow, RowFlow } from "./common/Layout.jsx"; import { Add, Subtract, Target } from "./common/Icons.jsx"; import ErrorMessage from "./common/ErrorMessage.jsx"; +/** + * CaseContainer serves as the main component for displaying and interacting with an assurance case. + * It integrates various components such as MermaidChart for visual representation, ItemEditor for editing case items, + * and CaseTopBar for additional case management functions. This component handles loading of case data, + * user authentication, and provides zoom and pan functionality for the case diagram. + * + * @returns {JSX.Element} Renders the assurance case container with editing capabilities and visualization controls. + */ function CaseContainer() { const { caseSlug } = useParams(); const theme = useTheme(); @@ -120,13 +128,16 @@ function CaseContainer() { } }, [assuranceCase]); + /** + * Generates a unique identifier for new elements within the assurance case based on the type and its parents. + * It prefixes the identifier based on the type and ensures uniqueness within the case. + * + * @param {string} type - The type of the element for which the ID is being generated. + * @param {string} parentId - The ID of the parent element. + * @param {string} parentType - The type of the parent element. + * @returns {string} A unique identifier for the new element. + */ const getIdForNewElement = useCallback( - /** - * @param {string} type - * @param {string} parentId - * @param {string} parentType - * @returns {string} - */ (type, parentId, parentType) => { let prefix = configData.navigation[type].db_name .substring(0, 1) @@ -154,6 +165,11 @@ function CaseContainer() { [assuranceCase, identifiers], ); + /** + * Updates all identifiers within the assurance case to ensure they are unique. + * This function might be necessary when there are changes to the case structure + * or to correct any identifier conflicts. + */ const updateAllIdentifiers = useCallback(() => { setIsLoading(true); @@ -381,7 +397,13 @@ function CaseContainer() { ); } -/** @returns {string[]} */ +/** + * Generates a list of identifiers from the assurance case. It recursively visits + * each item in the case structure, collecting the names to form a set of identifiers. + * + * @param {Object} assuranceCase - The assurance case object from which to generate the list. + * @returns {string[]} A list of unique identifiers derived from the assurance case items. + */ function updateIdList(assuranceCase) { const set = []; assuranceCase.goals.forEach((goal) => { diff --git a/frontend/src/components/CaseCreator.js b/frontend/src/components/CaseCreator.js index 59a61c21..88c9b7fa 100644 --- a/frontend/src/components/CaseCreator.js +++ b/frontend/src/components/CaseCreator.js @@ -6,6 +6,18 @@ import CaseImporterFlow from "./CaseImporterFlow.jsx"; import ModalDialog from "./common/ModalDialog.jsx"; import useId from "@mui/utils/useId"; +/** + * CaseCreator component that toggles between the CaseCreatorFlow and CaseImporterFlow based on user action. + * It presents a modal dialog which either guides the user through creating a new assurance case + * or importing an existing one. The component ensures that a user is logged in before allowing case creation + * or importation. + * + * @param {Object} props - Component props. + * @param {boolean} props.isOpen - Determines if the modal dialog is open. + * @param {Function} props.onClose - Handler called when the modal dialog is requested to close. + * @param {boolean} props.isImport - Flag determining which flow to show: true for import, false for creation. + * @returns {JSX.Element|null} The rendered component if the user is logged in, otherwise null. + */ function CaseCreator({ isOpen, onClose, isImport }) { const titleId = useId(); diff --git a/frontend/src/components/CaseCreatorFlow.jsx b/frontend/src/components/CaseCreatorFlow.jsx index 5d7d9ec5..992766dd 100644 --- a/frontend/src/components/CaseCreatorFlow.jsx +++ b/frontend/src/components/CaseCreatorFlow.jsx @@ -10,10 +10,23 @@ import LoadingSpinner from "./common/LoadingSpinner.jsx"; import { ArrowRight } from "./common/Icons.jsx"; import ErrorMessage from "./common/ErrorMessage.jsx"; -// see models.py +/** + * Maximum allowed lengths for title and description, + * see /eap_backend/eap_api/models.py + */ const titleMaxLength = 200; const descriptionMaxLength = 1000; + +/** + * CaseCreatorFlow component guides the user through the process of creating a new assurance case. + * It consists of two stages: entering basic case details (title and description), + * and selecting a template for the case. Upon completion, the case is posted to the server. + * + * @param {Object} props Component props. + * @param {string} props.titleId A unique ID for the title element, used for accessibility. + * @param {Function} props.onClose Function to call when the user chooses to close the modal. + */ function CaseCreatorFlow({ titleId, onClose }) { const [stage, setStage] = useState(0); diff --git a/frontend/src/components/CaseImporterFlow.jsx b/frontend/src/components/CaseImporterFlow.jsx index 33f70faa..519d2301 100644 --- a/frontend/src/components/CaseImporterFlow.jsx +++ b/frontend/src/components/CaseImporterFlow.jsx @@ -17,6 +17,14 @@ import FileInput from "./common/FileInput.jsx"; import { ArrowRight } from "./common/Icons.jsx"; import ErrorMessage from "./common/ErrorMessage.jsx"; +/** + * CaseImporterFlow allows users to import an assurance case into the TEA Platform from either a file or a URL. + * It supports importing from SVG files with embedded JSON metadata or directly from JSON files. + * + * @param {Object} props The component props. + * @param {string} props.titleId A unique identifier for the title element, used for accessibility. + * @param {Function} props.onClose A function to call when closing the import modal. + */ function CaseImporterFlow({ titleId, onClose }) { const [uploadType, setUploadType] = useState("file"); const [url, setUrl] = useState(""); @@ -33,6 +41,11 @@ function CaseImporterFlow({ titleId, onClose }) { const baseURL = `${getBaseURL()}`; const navigate = useNavigate(); + /** Parses SVG text to extract embedded JSON metadata + * @param {string} text The SVG text to parse + * @returns {Promise} The parsed JSON metadata + * @throws {Error} If the metadata cannot be parsed + */ const parseSvg = useCallback(async (text) => { const parser = new DOMParser(); const svgDoc = parser.parseFromString(text, "image/svg+xml"); @@ -48,8 +61,13 @@ function CaseImporterFlow({ titleId, onClose }) { } }, []); + /** Fetches content from a URL and tries to parse it as JSON or SVG + * + * @param {string} url + * @returns {Promise} The parsed JSON or SVG content + * @throws {Error} If the content cannot be loaded or parsed + */ const getUrlContent = useCallback( - /** @param {string} url */ async (url) => { try { const response = await fetch(url); @@ -75,6 +93,13 @@ function CaseImporterFlow({ titleId, onClose }) { [parseSvg] ); + /** + * Posts the JSON representation of a case to the backend + * + * @param {Object} json The case JSON to post + * @returns {Promise} + * @throws {Error} If the JSON cannot be posted + */ const postCaseJSON = useCallback( (json) => { const requestOptions = { @@ -108,6 +133,13 @@ function CaseImporterFlow({ titleId, onClose }) { [token, baseURL, navigate] ); + /** + * Handles form submission for importing a case + * + * @param {Event} e The form submission event + * @returns {void} + * @throws {Error} If the form submission fails + */ const onSubmit = useCallback( (e) => { e.preventDefault(); @@ -132,11 +164,22 @@ function CaseImporterFlow({ titleId, onClose }) { }, [uploadType, url, fileJson, getUrlContent, postCaseJSON] ); - + + /** + * Handles changes in the selected upload type (file or URL) + * @param {Event} e The change event + * @returns {void} + * @throws {Error} If the change event fails + */ const onTypeChange = useCallback((e) => { setUploadType(e.target.value); }, []); + /** + * Processes the selected file to extract JSON data. + * + * @returns {void} + */ useEffect(() => { if (!file) { setFileJson(null); diff --git a/frontend/src/components/CaseMediaPreview.jsx b/frontend/src/components/CaseMediaPreview.jsx index 46aa2b1e..761c9d11 100644 --- a/frontend/src/components/CaseMediaPreview.jsx +++ b/frontend/src/components/CaseMediaPreview.jsx @@ -9,12 +9,29 @@ import { getCase } from "./caseApi"; import { Box } from "@mui/material"; import { LoadingCard } from "./ManageCases"; +/** + * CaseMediaPreview dynamically renders a visual preview of an assurance case. + * Depending on the configuration, it either displays a Mermaid chart representation of the case + * or a static mockup image. This component is intended to enhance the user interface by providing + * a quick glance at the case structure or content. + * + * @param {Object} props - Component props. + * @param {Object} props.caseObj - The case object containing information such as the case ID. + * @returns {JSX.Element} A visual representation of the assurance case. + */ export const CaseMediaPreview = ({ caseObj }) => { const theme = useTheme(); const [token] = useLoginToken(); const [assuranceCase, setAssuranceCase] = useState(); const [isLoading, setIsLoading] = useState(true); + /** + * Fetch the detailed assurance case data when the component mounts. + * + * @param {string} token - The user's login token. + * @param {Object} caseObj - The case object containing information such as the case ID. + * @returns {void} + */ useEffect(() => { if (token) { let isMounted = true; @@ -31,12 +48,14 @@ export const CaseMediaPreview = ({ caseObj }) => { // TODO show error to user }); + // Cleanup function to handle component unmount return () => { isMounted = false; }; } }, [token, caseObj]); + // Conditionally render the Mermaid chart or a static image based on configuration if (configData.use_case_preview_svg) { return ( <> diff --git a/frontend/src/components/CasePermissionsManager.js b/frontend/src/components/CasePermissionsManager.js index 4f1c1bcf..6070642f 100644 --- a/frontend/src/components/CasePermissionsManager.js +++ b/frontend/src/components/CasePermissionsManager.js @@ -12,6 +12,17 @@ import { getCase } from "./caseApi.js"; import { useLoginToken } from "../hooks/useAuth.js"; import ErrorMessage from "./common/ErrorMessage.jsx"; +/** + * CasePermissionsManager serves as a modal dialog for managing group permissions for a specific assurance case within the TEA Platform. It provides an interface for viewing and editing the access levels (view or edit) of various groups associated with the case. + * + * @param {Object} props - Component props. + * @param {string} props.caseId - The unique identifier of the assurance case. + * @param {Object} props.assuranceCase - The assurance case object. + * @param {boolean} props.isOpen - Controls the visibility of the modal dialog. + * @param {Function} props.onClose - Callback function that is called when the modal is requested to be closed. + * @param {Function} props.onSuccess - Callback function that is called after successfully updating permissions. + * @returns {JSX.Element} A modal dialog for managing group permissions. + */ function CasePermissionsManager({ caseId, assuranceCase, @@ -38,6 +49,16 @@ function CasePermissionsManager({ ); } +/** + * CasePermissionsManagerInner is the core component within the CasePermissionsManager modal dialog, responsible for the actual management of group permissions. It allows users to assign 'view' or 'edit' permissions to groups for the specified assurance case, or remove their access entirely. + * + * @param {Object} props - Component props. + * @param {string} props.caseId - The unique identifier of the assurance case for which permissions are being managed. + * @param {Object} props.assuranceCase - The assurance case object, used for preloading existing permissions. + * @param {Function} props.afterSubmit - Callback function that is called after permissions are successfully updated. + * @param {Function} props.onClose - Callback function to close the permissions manager. + * @returns {JSX.Element} The interface for managing group permissions, including a list of groups with selectable permissions and action buttons to submit changes or cancel the operation. + */ function CasePermissionsManagerInner({ caseId, assuranceCase, diff --git a/frontend/src/components/CaseTopBar.jsx b/frontend/src/components/CaseTopBar.jsx index 2b5007c1..0315d89a 100644 --- a/frontend/src/components/CaseTopBar.jsx +++ b/frontend/src/components/CaseTopBar.jsx @@ -20,6 +20,20 @@ import CommentSection from "./CommentSection.js"; import CasePermissionsManager from "./CasePermissionsManager.js"; import { DisguisedTextInput } from "./common/TextInput.jsx"; +/** + * CaseTopBar provides a top navigation bar for the assurance case page within the TEA Platform, offering various functionalities such as editing the case title, adding goals, managing accessibility settings, exporting, adding notes, managing permissions, and deleting the case. It enhances user interaction by providing quick access to these features directly from the case view. + * + * @param {Object} props - Component props. + * @param {Object} props.sx - The style properties applied to the component. + * @param {Object} props.assuranceCase - The current assurance case object, containing case details. + * @param {string} props.caseId - The unique identifier for the current assurance case. + * @param {Function} props.onRefresh - Callback function to refresh the case view after certain actions. + * @param {Function} props.setErrors - Callback function to handle errors and display them to the user. + * @param {Function} props.getIdForNewElement - Function to generate IDs for new case elements. + * @param {Function} props.updateAllIdentifiers - Function to update all identifiers/names within the case, ensuring uniqueness. + * @param {Function} props.setSelected - Function to set the currently selected item in the case. + * @returns {JSX.Element} The top navigation bar with case management features. + */ function CaseTopBar({ sx, assuranceCase, @@ -41,6 +55,12 @@ function CaseTopBar({ const [permissionsOpen, setPermissionsOpen] = useState(false); const [deleteOpen, setDeleteOpen] = useState(false); + /** + * Set the case name to the provided value. + * + * @param {string} name - The new name for the case. + * @returns {void} + */ const setCaseName = useCallback( (name) => { editCase(token, caseId, { name }) @@ -53,6 +73,12 @@ function CaseTopBar({ [token, caseId, onRefresh] ); + /** + * Add a new goal to the assurance case. + * + * @returns {void} + * @throws {Error} If the goal cannot be added. + */ const addGoal = useCallback(() => { createItem( token, diff --git a/frontend/src/components/CommentSection.js b/frontend/src/components/CommentSection.js index 6ff3eeb7..02da9e1c 100644 --- a/frontend/src/components/CommentSection.js +++ b/frontend/src/components/CommentSection.js @@ -18,6 +18,15 @@ import { visuallyHidden } from "@mui/utils"; import TableSortLabel from "@mui/material/TableSortLabel"; import Box from "@mui/material/Box"; +/** + * CommentSection provides an interface for users to view and add comments to an assurance case. It presents a modal dialog with a form to submit new comments and a list of existing comments. + * + * @param {Object} props - Component props. + * @param {string} props.caseId - The unique identifier of the assurance case to which comments are related. + * @param {boolean} props.isOpen - Boolean state to control the visibility of the comment section modal. + * @param {Function} props.onClose - Function to call when closing the comment section modal. + * @returns {JSX.Element} A modal dialog component that allows users to manage comments for an assurance case. + */ function CommentSection({ caseId, isOpen, onClose }) { const titleId = useId(); @@ -33,6 +42,14 @@ function CommentSection({ caseId, isOpen, onClose }) { ); } +/** + * CommentSectionInner handles the display and management of comments for a specific assurance case, including posting new comments and sorting existing ones. + * + * @param {Object} props - Component props. + * @param {string} props.assuranceCaseId - The unique identifier of the assurance case. + * @param {Function} props.onClose - Function to call when the user wishes to close the comment section. + * @returns {JSX.Element} The inner content of the comment section, including a form for new comments and a list of existing comments. + */ function CommentSectionInner({ assuranceCaseId, onClose }) { const [comments, setComments] = useState([]); const [error, setError] = useState(""); @@ -45,6 +62,11 @@ function CommentSectionInner({ assuranceCaseId, onClose }) { const [token] = useLoginToken(); + /** + * Fetch comments from the server. + * + * @returns {undefined} + */ const fetchComments = useCallback(async () => { const url = `${getBaseURL()}/comments/${assuranceCaseId}/`; const requestOptions = { @@ -58,10 +80,21 @@ function CommentSectionInner({ assuranceCaseId, onClose }) { setComments(data); }, [assuranceCaseId, token]); + /** + * Fetch comments when the component mounts. + * + * @returns {undefined} + */ useEffect(() => { fetchComments(); }, [fetchComments]); + /** + * Post a new comment to the server. + * + * @param {Event} e - The form submission event. + * @returns {undefined} + */ const onSubmit = useCallback( async (e) => { e.preventDefault(); @@ -100,6 +133,12 @@ function CommentSectionInner({ assuranceCaseId, onClose }) { [assuranceCaseId, token, fetchComments, newComment], ); + /** + * Sort comments by a given property. + * + * @param {string} property - The property to sort by. + * @returns {undefined} + */ const onSort = (property) => { const opositeDir = sort.direction === "asc" ? "desc" : "asc"; const direction = sort.property === property ? opositeDir : sort.direction; diff --git a/frontend/src/components/CreateGroup.js b/frontend/src/components/CreateGroup.js index c1f75f68..56920ba4 100644 --- a/frontend/src/components/CreateGroup.js +++ b/frontend/src/components/CreateGroup.js @@ -4,6 +4,15 @@ import { ColumnFlow, RowFlow } from "./common/Layout.jsx"; import { Button } from "@mui/material"; import TextInput from "./common/TextInput.jsx"; +/** + * CreateGroup is a form component used for creating a new group within the TEA Platform. It provides a simple interface for entering the name of the new group and submitting it to the server. Upon successful submission, the form invokes a callback function to reflect the change. + * + * @param {Object} props - Component props. + * @param {Function} props.afterSubmit - Callback function to be called after successfully creating a group. It is used to trigger any necessary updates in the parent component, such as refreshing the list of groups. + * @returns {JSX.Element} A form that allows users to input a name for a new group and create it. + * + * This component includes error handling to provide feedback to the user in case of an unsuccessful group creation attempt. It leverages the `TextInput` component for inputting the group's name and validates the input before submission to ensure that a name is provided. + */ function CreateGroup({ afterSubmit }) { const [name, setName] = useState(""); const [error, setError] = useState(); diff --git a/frontend/src/components/DeleteCaseModal.jsx b/frontend/src/components/DeleteCaseModal.jsx index 82b44005..98376bd2 100644 --- a/frontend/src/components/DeleteCaseModal.jsx +++ b/frontend/src/components/DeleteCaseModal.jsx @@ -9,6 +9,18 @@ import LoadingSpinner from "./common/LoadingSpinner.jsx"; import { Bin } from "./common/Icons.jsx"; import ErrorMessage from "./common/ErrorMessage.jsx"; +/** + * DeleteCaseModal presents a confirmation dialog for deleting an assurance case. It informs the user of the permanent consequences of this action and provides options to either cancel or proceed with the deletion. This component is critical for ensuring that users consciously acknowledge the deletion of an assurance case, preventing accidental data loss. + * + * @param {Object} props - Component props. + * @param {boolean} props.isOpen - Controls the visibility of the modal dialog. + * @param {Function} props.onClose - Callback function to be called when the modal is closed without deletion. + * @param {string} props.caseId - The unique identifier of the assurance case to be deleted. + * @param {Function} props.onDelete - Callback function to be called after the case has been successfully deleted. + * @returns {JSX.Element} A modal dialog that prompts users to confirm or cancel the deletion of an assurance case. + * + * The component handles the deletion process internally, including API communication and error handling. It displays a loading indicator while the deletion is in progress and provides feedback in case of errors. The use of `ModalDialog`, `Typography`, and `Button` components from Material UI ensures a consistent and accessible user interface. + */ function DeleteCaseModal({ isOpen, onClose, caseId, onDelete }) { const [loading, setLoading] = useState(false); const [errors, setErrors] = useState([]); @@ -18,6 +30,12 @@ function DeleteCaseModal({ isOpen, onClose, caseId, onDelete }) { const titleId = useId(); const descriptionId = useId(); + /** + * Handle the deletion of the assurance case. + * + * @returns {void} + * @throws {Error} If the deletion process fails. + */ const onDeleteClick = useCallback(() => { setLoading(true); setErrors([]); diff --git a/frontend/src/components/DeleteItemModal.jsx b/frontend/src/components/DeleteItemModal.jsx index 48e69ed6..8420104c 100644 --- a/frontend/src/components/DeleteItemModal.jsx +++ b/frontend/src/components/DeleteItemModal.jsx @@ -9,6 +9,20 @@ import LoadingSpinner from "./common/LoadingSpinner.jsx"; import { Bin } from "./common/Icons.jsx"; import ErrorMessage from "./common/ErrorMessage.jsx"; +/** + * DeleteItemModal presents a confirmation dialog for deleting an item (e.g., goal, context, claim) within an assurance case. This component is crucial for ensuring that users are fully aware of the permanent deletion of the item and any associated links. It provides users with a clear choice to either proceed with the deletion or cancel the action to prevent accidental data loss. + * + * @param {Object} props - Component props. + * @param {boolean} props.isOpen - Controls the visibility of the modal dialog. + * @param {Function} props.onClose - Callback function to be called when the modal is closed without deletion. + * @param {string} props.id - The unique identifier of the item to be deleted. + * @param {string} props.type - The type of the item to be deleted (e.g., "TopLevelNormativeGoal", "Context"). + * @param {string} props.name - The name of the item to be deleted, displayed in the modal for clarity. + * @param {Function} props.onDelete - Callback function to be called after the item has been successfully deleted. + * @returns {JSX.Element} A modal dialog that prompts users to confirm or cancel the deletion of an item within an assurance case. + * + * The component manages the deletion process, including API communication and error handling, and displays a loading indicator while the deletion is in progress. Through the use of Material UI components like `ModalDialog`, `Typography`, and `Button`, it ensures a consistent and accessible user interface, while the `ErrorMessage` component provides feedback in case of errors. + */ function DeleteItemModal({ isOpen, onClose, id, type, name, onDelete }) { const [loading, setLoading] = useState(false); const [errors, setErrors] = useState([]); @@ -18,6 +32,12 @@ function DeleteItemModal({ isOpen, onClose, id, type, name, onDelete }) { const titleId = useId(); const descriptionId = useId(); + /** + * Handle the deletion of the item. + * + * @returns {void} + * @throws {Error} If the deletion process fails. + */ const onDeleteClick = useCallback(() => { setLoading(true); setErrors([]); diff --git a/frontend/src/components/ExportCaseModal.jsx b/frontend/src/components/ExportCaseModal.jsx index 0d239452..1efd29b8 100644 --- a/frontend/src/components/ExportCaseModal.jsx +++ b/frontend/src/components/ExportCaseModal.jsx @@ -20,6 +20,18 @@ import { getCase } from "./caseApi.js"; import { useLoginToken } from "../hooks/useAuth.js"; import ErrorMessage from "./common/ErrorMessage.jsx"; +/** + * ExportCaseModal provides a user interface for exporting an assurance case in either JSON or SVG format. It allows users to select their preferred export format and initiates the download process. This component ensures that users can easily export and save their work for external use or archival purposes. + * + * @param {Object} props - Component props. + * @param {boolean} props.isOpen - Controls the visibility of the export modal. + * @param {Function} props.onClose - Callback function to close the export modal. + * @param {string} props.caseId - The unique identifier of the assurance case to be exported. + * @param {Object} props.assuranceCase - The loaded assurance case object. If not provided, the case will be fetched using the provided caseId. + * @returns {JSX.Element} A modal dialog that provides options to export the assurance case in selected format. + * + * The component handles the export process based on the selected format: for JSON, it uses `neatJSON` to format the case data and `file-saver` library to initiate the download; for SVG, it utilizes a custom SVGDownloader class to generate and download the SVG representation of the case. It supports dynamic loading of the assurance case if not provided and handles errors during the export process. + */ function ExportCaseModal({ isOpen, onClose, caseId, assuranceCase }) { const [format, setFormat] = useState("json"); const [isLoading, setIsLoading] = useState(false); @@ -34,6 +46,13 @@ function ExportCaseModal({ isOpen, onClose, caseId, assuranceCase }) { setFormat(e.target.value); }, []); + /** + * Handle the export of the assurance case. + * + * @param {Event} e - The form submit event. + * @returns {void} + * @throws {Error} If the export process fails. + */ const onSubmit = useCallback( async (e) => { e.preventDefault(); diff --git a/frontend/src/components/Home.js b/frontend/src/components/Home.js index 07849a41..e9960096 100644 --- a/frontend/src/components/Home.js +++ b/frontend/src/components/Home.js @@ -6,6 +6,15 @@ import Login from "./Login"; import { ColumnFlow } from "./common/Layout"; import splashImage from "../images/building-an-assurance-case-adjusted-aspect-ratio.png"; +/** + * Splash presents a visually engaging splash screen for users not logged in or when a page is not found. It displays a background image with an option for user login or a not found message. This component is the initial view for users accessing the platform, guiding them to login for further interaction. + * + * @param {Object} props - Component props. + * @param {boolean} props.notFound - Indicates whether the splash screen is shown as a result of a 404 not found error. + * @returns {JSX.Element} A layout with a background image on one side and a login component or not found message on the other. + * + * The splash screen is designed to be responsive and visually appealing, setting the tone of the application. It utilizes the Material UI Box and Typography components for layout and text display. The choice between showing a login form and a not found message is determined by the `notFound` prop. This component plays a crucial role in user experience by providing a clear entry point for authentication or notifying users when a requested page is unavailable. + */ export const Splash = ({ notFound }) => { // TODO #302 add content to splash screen const theme = useTheme(); @@ -57,11 +66,22 @@ export const Splash = ({ notFound }) => { ); }; + +/** + * Home serves as the main entry point for users, directing them to either manage their cases if logged in or to the splash screen if not. It checks the authentication status and dynamically renders the appropriate component based on the user's login state. + * + * @returns {JSX.Element} Either the ManageCases component for logged-in users or the Splash component for guests. + * + * This component uses the `useLoginToken` hook to determine if a user is authenticated. If a token is present, indicating the user is logged in, the ManageCases component is rendered, allowing the user to interact with their assurance cases. If no token is found, the Splash component is displayed, prompting the user to log in or indicating that the page is not found. This component orchestrates the primary user flow of the application based on authentication status. + */ export const Home = () => { const [isLoggedIn, setIsLoggedIn] = useState(false); const [token] = useLoginToken(); + /** + * Update the login status when the token changes. + */ useEffect(() => { setIsLoggedIn(token != null); }, [token]); diff --git a/frontend/src/components/ItemEditor.js b/frontend/src/components/ItemEditor.js index 50e5b907..65d89a67 100644 --- a/frontend/src/components/ItemEditor.js +++ b/frontend/src/components/ItemEditor.js @@ -14,6 +14,12 @@ import TextInput from "./common/TextInput.jsx"; import SelectInput from "./common/SelectInput.jsx"; import ErrorMessage from "./common/ErrorMessage.jsx"; +/** + * niceNameforType returns a human-readable name for the given type. + * + * @param {string} type - The type of the item. + * @returns {string} A human-readable name for the given type. + */ function niceNameforType(type) { switch (type) { case "TopLevelNormativeGoal": @@ -30,6 +36,21 @@ function niceNameforType(type) { } } +/** + * AddItemButton provides a button interface for adding a new item (Goal, Context, Claim, or Evidence) as a child to a specified parent within an assurance case. It creates a new item of the specified type and links it to the parent item, then refreshes the view and selects the newly created item. + * + * @param {Object} props - Component props. + * @param {string} props.childType - The type of item to be created. + * @param {string} props.parentId - The ID of the parent item to which the new item will be linked. + * @param {string} props.parentType - The type of the parent item. + * @param {Function} props.onRefresh - Function to refresh the view after the item is added. + * @param {Function} props.setErrors - Function to display errors. + * @param {Function} props.getIdForNewElement - Function to generate a new ID for the item being created. + * @param {Function} props.setSelected - Function to set the newly created item as selected in the UI. + * @returns {JSX.Element} A button that triggers the creation of a new item when clicked. + * + * This component simplifies the process of adding new items to the assurance case by handling the API call and subsequent UI updates. + */ function AddItemButton({ childType, parentId, @@ -41,6 +62,11 @@ function AddItemButton({ }) { const [token] = useLoginToken(); + /** + * Handle the click event for adding a new item. + * + * @returns {void} + */ const onClick = useCallback(() => { createItem( token, @@ -80,6 +106,21 @@ function AddItemButton({ ); } +/** + * PropertyField allows editing of a single property (field) of an item within an assurance case. It supports text input and updates the backend upon change. It is used for editing properties like name, description, and URL of items. + * + * @param {Object} props - Component props. + * @param {string} props.id - The ID of the item being edited. + * @param {string} props.type - The type of the item being edited. + * @param {Object} props.item - The current state of the item being edited. + * @param {string} props.fieldName - The name of the field in the item to be edited. + * @param {Function} props.onRefresh - Function to refresh the parent view upon successful edit. + * @param {boolean} props.mermaidFocus - Indicates if the field is focused in the Mermaid diagram. + * @param {Object} [props...props] - Additional props passed to the TextInput component. + * @returns {JSX.Element} A text input field for editing a property of an item. + * + * This component abstracts the input field logic for editing item properties, handling validation, and API update calls. + */ function PropertyField({ id, type, @@ -93,6 +134,13 @@ function PropertyField({ const [token] = useLoginToken(); + /** + * Handle the change event for the input field. + * + * @param {string} value - The new value of the input field. + * @returns {void} + * @throws {Error} If the field cannot be changed. + */ const setValue = useCallback( (value) => { if (item[fieldName] !== value) { @@ -133,6 +181,23 @@ function PropertyField({ ); } +/** + * PropertySelect provides a dropdown selection interface for changing a specific property of an item within an assurance case. It is used for fields where a selection from predefined options is required, like the claim type of a PropertyClaim. + * + * @param {Object} props - Component props. + * @param {string} props.label - The label for the select field. + * @param {string} props.id - The ID of the item being edited. + * @param {string} props.type - The type of the item being edited. + * @param {Object} props.item - The current state of the item being edited. + * @param {Function} props.setItem - Function to set the updated item state. + * @param {string} props.fieldName - The name of the field in the item to be edited. + * @param {Function} props.onRefresh - Function to refresh the parent view upon successful edit. + * @param {Array} props.options - The options for the dropdown. + * @param {Object} [props...props] - Additional props passed to the SelectInput component. + * @returns {JSX.Element} A dropdown select field for editing a specific property of an item. + * + * This component simplifies the process of selecting from predefined options for a specific item property, handling the update logic and UI feedback. + */ function PropertySelect({ label, id, @@ -148,6 +213,13 @@ function PropertySelect({ const [token] = useLoginToken(); + /** + * Handle the change event for the select field. + * + * @param {string} value - The new value of the select field. + * @returns {void} + * @throws {Error} If the field cannot be changed. + */ const setValue = useCallback( (value) => { if (item[fieldName] !== value) { @@ -191,6 +263,23 @@ function PropertySelect({ ); } +/** + * ItemEditor provides an interface for editing the details of a specific item within an assurance case, such as goals, contexts, claims, or evidence. It allows for editing textual properties, linking to parents, and deleting the item. + * + * @param {Object} props - Component props. + * @param {string} props.caseId - The ID of the assurance case to which the item belongs. + * @param {string} props.id - The ID of the item being edited. + * @param {string} props.type - The type of the item being edited. + * @param {Function} props.onRefresh - Function to refresh the view after editing. + * @param {Function} props.onHide - Function to hide the editor. + * @param {Function} props.getIdForNewElement - Function to generate a new ID for linking items. + * @param {Function} props.setSelected - Function to select an item in the UI. + * @param {boolean} props.graphUpdate - Flag indicating if the graph should be updated. + * @param {boolean} props.mermaidFocus - Indicates if the item is focused in the Mermaid diagram. + * @returns {JSX.Element} An interface for editing an item's details. + * + * This component encapsulates the functionality required for editing items within an assurance case, providing fields for editing, options for linking to other items, and actions for deleting the item. + */ function ItemEditor({ caseId, id, @@ -213,6 +302,12 @@ function ItemEditor({ const [token] = useLoginToken(); + /** + * Fetch the item from the server. + * + * @returns {void} + * @throws {Error} If ... + */ const updateItem = useCallback(() => { if (token) { setLoading(true); @@ -249,9 +344,11 @@ function ItemEditor({ } }, [token, id, type]); - // Fetch item when selected node in graph changes, but **not** for every graph update. - // Graph updates occur on an interval, and updating the item on this interval re-renders the - // ItemEditor. + /** + * Fetch the item when the selected node in the graph changes, but **not** for every graph update. Graph updates occur on an interval, and updating the item on this interval re-renders the ItemEditor. + * + * @returns {void} + */ useEffect(() => { updateItem(); }, [token, id, type]); @@ -269,6 +366,11 @@ function ItemEditor({ onHide(); }, [onRefresh, onHide]); + /** + * Add a parent to the item. + * + * @returns {void} + */ const submitAddParent = useCallback(() => { if (!parentToAdd) { return; @@ -301,6 +403,11 @@ function ItemEditor({ } }, [parentToAdd, item, token, id, type, onRefresh]); + /** + * Remove a parent from the item. + * + * @returns {void} + */ const submitRemoveParent = useCallback(() => { if (!parentToRemove) { return; @@ -414,7 +521,7 @@ function ItemEditor({ name={item.name} /> {configData.navigation[type].children.length || - configData.navigation[type]["parent_relation"] === + configData.navigation[type]["parent_relation"] === "many-to-many" ? ( <> Link to {item.name} @@ -431,7 +538,7 @@ function ItemEditor({ /> ))} {configData.navigation[type]["parent_relation"] === - "many-to-many" ? ( + "many-to-many" ? ( <> { const [username, setUsername] = useState(""); const [password, setPassword] = useState(""); diff --git a/frontend/src/components/Logout.js b/frontend/src/components/Logout.js index 6bedc4f4..cbc8251b 100644 --- a/frontend/src/components/Logout.js +++ b/frontend/src/components/Logout.js @@ -6,11 +6,22 @@ import { ColumnFlow, ModalLikeLayout, RowFlow } from "./common/Layout"; import { Button, Typography } from "@mui/material"; import { useEnforceLogin, useLoginToken } from "../hooks/useAuth.js"; +/** + * Logout is a form component used for logging out of the TEA Platform. It provides a simple interface for logging out and redirects to the login page upon successful logout. + * + * @returns {JSX.Element} A form that allows users to log out of the platform. + */ const Logout = () => { const { sessionExpired } = useParams(); useEnforceLogin(); const [token, setToken] = useLoginToken(); + /** + * Handle logout request. + * + * @param {Event} e - The event object. + * @returns {void} + */ const handleLogout = useCallback( (e) => { e.preventDefault(); diff --git a/frontend/src/components/ManageCases.jsx b/frontend/src/components/ManageCases.jsx index b37576ba..3324e9b9 100644 --- a/frontend/src/components/ManageCases.jsx +++ b/frontend/src/components/ManageCases.jsx @@ -26,6 +26,12 @@ import DeleteCaseModal from "./DeleteCaseModal"; import ErrorMessage from "./common/ErrorMessage"; import { CaseMediaPreview } from "./CaseMediaPreview"; +/** + * ThemedCard is a wrapper component that standardizes the appearance of cards in the ManageCases view. It applies a theme-based styling to ensure consistency across different parts of the application. + * + * @param {Object} props - Component props including standard Card props and additional style overrides. + * @returns {JSX.Element} A Card component with applied theme styles. + */ const ThemedCard = ({ sx, ...props }) => { return ( { ); }; +/** + * CreateCard provides a UI element for initiating the creation of a new assurance case. It displays a card styled according to the application theme, with an action area that, when clicked, opens the case creation modal. + * + * @param {Function} onCreateClick - Callback function to be called when the card is clicked. + * @returns {JSX.Element} A card that triggers the case creation process when clicked. + */ const CreateCard = ({ onCreateClick }) => { const theme = useTheme(); @@ -72,12 +84,22 @@ const CreateCard = ({ onCreateClick }) => { ); }; +/** + * formatter is an instance of Intl.DateTimeFormat that formats dates in the "short" format, including the month, day, and year. + */ const formatter = new Intl.DateTimeFormat(undefined, { month: "short", day: "2-digit", year: "numeric", }); +/** + * CaseCard displays a single assurance case in card format within the ManageCases view. It includes a preview of the case, the case name, description, and action buttons for case operations like edit, delete, and more. + * + * @param {Object} caseObj - An object containing the details of the assurance case to display. + * @param {Function} reload - A function to reload the list of cases, called after certain operations like delete. + * @returns {JSX.Element} A card representing an assurance case with actionable items. + */ const CaseCard = ({ caseObj, reload }) => { const theme = useTheme(); @@ -241,6 +263,11 @@ const CaseCard = ({ caseObj, reload }) => { ); }; +/** + * LoadingCard displays a placeholder card with a loading indicator. It is used in the ManageCases view while assurance case data is being loaded from the backend. + * + * @returns {JSX.Element} A card with a loading spinner, indicating data is being loaded. + */ export const LoadingCard = () => { return ( @@ -249,6 +276,13 @@ export const LoadingCard = () => { ); }; +/** + * ManageCases is the main component for managing assurance cases. It displays a list of assurance cases each represented by a CaseCard, and provides options to create a new case or import cases from files. + * + * @returns {JSX.Element} A layout including a list of assurance cases, and options for creating or importing cases. + * + * This component integrates several functionalities including case creation, import, and display. It fetches and displays assurance cases from the backend, handling loading states and errors. It also provides entry points for case creation and import through modal dialogs. + */ const ManageCases = () => { const [isLoading, setIsLoading] = useState(true); const [cases, setCases] = useState([]); @@ -259,6 +293,12 @@ const ManageCases = () => { useEnforceLogin(); const [token] = useLoginToken(); + /** + * doLoad is a memoized callback function that fetches assurance cases from the backend and updates the component state with the loaded data. It handles loading states and errors, and is called when the component mounts or when the token changes. + * + * @returns {Function} A memoized callback function to fetch assurance cases from the backend and update the component state. + * @throws {Error} If the fetch process fails with a 401 status code. + */ const doLoad = useCallback(() => { let isMounted = true; @@ -278,10 +318,11 @@ const ManageCases = () => { case 401: unauthorized(); break; + // TODO: add default case? } }, - (reason) => { - console.log(reason); + (err) => { + console.log(err); setError("Something went wrong. Please try again later."); } ) @@ -312,7 +353,9 @@ const ManageCases = () => { }; }, [token]); - // initial load + /** + * Load the assurance cases from the backend when the component mounts. + */ useEffect(() => { doLoad(); }, [doLoad]); diff --git a/frontend/src/components/Mermaid.js b/frontend/src/components/Mermaid.js index 7455dede..ec4ef39d 100644 --- a/frontend/src/components/Mermaid.js +++ b/frontend/src/components/Mermaid.js @@ -3,6 +3,18 @@ import mermaid from "mermaid"; import "./Mermaid.scss"; import { jsonToMermaid } from "./utils"; +/** + * MermaidChart is a component for rendering assurance case diagrams using the Mermaid library. It takes a JSON representation of an assurance case and renders it as a flowchart. + * + * @param {Object} props - Component props. + * @param {string} props.caseId - The ID of the assurance case to render. + * @param {Object} props.assuranceCase - The JSON representation of the assurance case to render. + * @param {string} props.selectedId - The ID of the currently selected node in the assurance case. + * @param {string} props.selectedType - The type of the currently selected node in the assurance case. + * @param {Function} props.setSelected - A function to set the currently selected node in the assurance case. + * @param {Function} props.setMermaidFocus - A function to set the focus state of the Mermaid chart. + * @returns {JSX.Element} A Mermaid chart component. + */ function MermaidChart({ caseId, assuranceCase, @@ -13,6 +25,12 @@ function MermaidChart({ }) { const [collapsedNodes, setCollapsedNodes] = useState([]); + /** + * Convert the assurance case to a Mermaid markdown representation. + * + * @type {string} + * @returns {string} The Mermaid markdown representation of the assurance case. + */ const chartmd = useMemo(() => { return jsonToMermaid( assuranceCase, @@ -22,12 +40,20 @@ function MermaidChart({ ); }, [assuranceCase, selectedType, selectedId, collapsedNodes]); - // refresh state + /** + * Refresh the state of the collapsed nodes when the assurance case changes. + * + * @returns {void} + */ useEffect(() => { setCollapsedNodes([]); }, [caseId]); - // initialise mermaid + /** + * Initialize the Mermaid library. + * + * @returns {void} + */ useEffect(() => { mermaid.initialize({ theme: "base", @@ -47,7 +73,9 @@ function MermaidChart({ }); }, []); - // set click callback + /** + * Set the selected node when a node is clicked in the Mermaid chart. + */ useEffect(() => { window.callback = (e) => { setMermaidFocus((tog) => !tog); @@ -60,8 +88,14 @@ function MermaidChart({ }; }, [setSelected, setMermaidFocus]); + /** + * Handle the collapse/expand button click event. + * + * @param {MouseEvent} e - The click event. + * @returns {void} + */ const onCollapseButtonClick = useCallback( - /** @param {MouseEvent} e */ (e) => { + (e) => { const nodeKey = e.target?.dataset?.key; if (nodeKey == null) { return; @@ -81,7 +115,13 @@ function MermaidChart({ [], ); - // trigger mermaid reload + /** + * Trigger a re-render of the Mermaid chart when the markdown content changes. + * + * @returns {void} + * @throws {Error} If the Mermaid div is not found. + * @throws {Error} If there is an error rendering the Mermaid chart. + */ useEffect(() => { try { const mermaidDiv = document.querySelector(`.mermaid-${caseId}`); diff --git a/frontend/src/components/Navigation.js b/frontend/src/components/Navigation.js index 366713d4..57557ebb 100644 --- a/frontend/src/components/Navigation.js +++ b/frontend/src/components/Navigation.js @@ -6,6 +6,12 @@ import Typography from "@mui/material/Typography"; import Button from "@mui/material/Button"; import { useLoginToken } from "../hooks/useAuth"; +/** + * NavButton is a customized Button component designed to fit within the application's navigation bar. It applies specific styling to maintain visual consistency across all navigational buttons. + * + * @param {Object} props - Standard Button props with additional style overrides if needed. + * @returns {JSX.Element} A Button component styled for the application's navigation bar. + */ function NavButton({ sx, ...props }) { return (