Functional Requirements Document DCO User Information Flow

Version Description of Change Author Date

1.0 Document Creation Patrick West 20141109

1.1 Registration Information provided by user – Glossary B

Patrick West 20141127

1.2 Section numbering corrections, grammar and spelling corrections from

Peter Fox

Patrick WestPeter Fox

20141201

1.3 Added various external ID fields for user information. Added user requirement and functional

requirements for visualizing user informaiton

Patrick West 20141202

Version 1.3 Sign Off

__ Patrick West: Author__ John Erickson__ Frank Baker: Engagement__ Peter Fox: DCO-DS

DCO User Information Flow Functional Requirements 2

CONTENTS1 INTRODUCTION 4

1.1 Purpose 4

1.2 Scope 4

1.3 Background 4

1.4 References 4

1.5 Assumptions and Constraints 4

1.6 Document Overview 5

2 METHODOLOGY 5

3 FUNCTIONAL REQUIREMENTS 5

4.1 Context 5

4.2 User Requirements 5

4.3 Data Flow Diagrams 6

4.4 Logical Data Model/Data Dictionary 6

4.5 Functional Requirements 6

5 OTHER REQUIREMENTS 6

5.1 Interface Requirements 6

5.2 Data Conversion Requirements 7

5.3 Hardware/Software Requirements 7

5.4 Operational Requirements 7

APPENDIX A - GLOSSARY 11

DCO User Information Flow Functional Requirements 3

1 INTRODUCTION

A user has registered for a new account. At this point there is no information in either the DCO Information Portal at https://info.deepcarbon.net or in the DCO Community Portal at https://deepcarbon.net.

During the registration the user provided information, including at this point their given name, family name, email, username (uid), password, and the user’s organization.

1.1 Purpose

The purpose of these functional requirements is to make sure that we request from the user information to be kept within the system for the user, any and all information the user entered is put into the right places, that there is an individual profile for the person if one does not already exist in the information portal, and that the user is granted any and all permission they need as a new user, and be subscribed to the DCO newsletter.

1.2 Scope

These functional requirements cover the interaction between the DCO Single Sign-On System, the DCO Community Portal at https://deepcarbon.net, and the DCO Information Portal at https://info.deepcarbon.net.

The overall time to complete the information flow depends on the user, as the last piece to put in place requires the user to log in to the DCO Community Portal.

This document will not describe what information is seen by anonymous users viewing the contents of the system, or logged-in users who have access to view and possibly edit content.

1.3 Background

The DCO Single Sign-On system is responsible for account registration and the initial storage of the user’s information. Outside the scope of this document is user login, user single sign-on requirements, user lost password, and user change password.

The DCO Community Portal is responsible for allowing community members to coordinate activities, events, planning, community communication between community members, organization of community members into various groups, and more. The only information within this system will be used to make sure members are capable of performing these activities only.

The DCO Information Portal is responsible for maintaining any and all information within the Deep Carbon Observatory, including but not limited to, any and all information deemed needed about a DCO Community Member.

1.4 References

DCO Account Registration Use Case – Patrick West, John Erickson

DCO Account Accept/Deny via Email Use Case – Patrick West, John Erickson

DCO User Information Flow Functional Requirements 4

DCO User Admin Acts on List of Pending Requests Use Case – Patrick West, John Erickson

1.5 Assumptions and Constraints

Constraint – The DCO SSO system is not able to communicate with the DCO Community Portal (Drupal) to provide user information because the user account has not yet been created. There is a lot of processing within Drupal when a new user logs into the system for the first time that we do not feel confortable enough with overriding. For this reason we have decided to add functionality within Drupal to communicate with DCO SSO.

All systems are available within the system at the time of user registration.

All systems are available within the system at the time the user logs into the DCO Community Portal.

1.6 Document Overview

The first part of this document provides background for these functional requirements. The remainder of the document will provide information about the implementation of the requirements, the information needed to be maintained, and which component maintains the information, and how to transfer the information between the systems.

2 METHODOLOGY

These functional requirements start with the user registration. It is at this point that we decide what information is to be required of the user in order to register and where and how that information is stored.

Once the registration has been accepted by the DCO User Admin the system needs to push any of this information to the DCO Information Portal.

When the user logs into the DCO Community Portal for the first time the system needs to fill in any information required within Drupal, user permissions updated, and the user subscribed to the DCO Newsletter.

3 FUNCTIONAL REQUIREMENTS

4.1 Context Diagram

The system components described here include the DCO Single Sign-On system, with which the user initially interacts with and registration information is stored; the User Admin interaction with the DCO Single Sign-On system in order to accept or deny the account registration; the DCO Information Portal, where the information is initially pushed once the registration request has been accepted by the DCO User Admin; and the DCO Community Portal once the user initially logs in.

DCO User Information Flow Functional Requirements 5

Exhibit 2 - Generic Context Diagram

4.2 User Requirements

4.2.1 New User

The user registers for a new account by providing information about themselves. The password provided during registration is required to be secure within the system. The information provided is to be used to populate information within other components of the system in order to allow the user to show up in member pages, group pages, search and browse functionality, and so on. The information requested should provide basic information for the user.

UR1 – User information collected to used in all the components of the system

UR2 – User information collected to provide the user with login ability to various system components

UR3 – User information collected to provide the user with subscription to DCO Newsletter

4.2.2 DCO User Administrator

DCO User Administrators can use the information provided by the user in order to assist them in determining whether or not to accept the user’s account registration request.

DCO User Information Flow Functional Requirements 6

There should be enough information collected by the system to help the DCO User Administrators.

UR4 – User information accessible to make determination to accept or deny account request

4.2.3 DCO Information Portal

The information portal requires user information in order to provide relationships between the user and artifacts of the community, such as but not limited to, datasets, instruments, publications, projects and field studies.

UR5 – Determine if the user already has a profile within the system

UR6 – If user already exists within the DCO Information Portal then the information collected will tie the user to their profile.

UC7 – If user does not already exist within the DCO Information Portal then the information collected will be enough to create the individual within the system, giving them both a URI and a DCO-ID.

UC8 – User information collected will give access for the user to login to the DCO Information Portal and have self-edit capabilities.

4.2.4 DCO Community Portal

The community portal requires enough user information in order to provide the user with the proper authorization to participate in various activities within the community such as, but not limited to, participation in the various communities and groups within the DCO and access to artifacts registered in the DCO portal.

UR9 – Information collected within the system will give the user authorization to participate and contribute to the various communities and groups within the DCO Community Portal.

UR10 – Information collected within the system will allow the user to login to the DCO Community Portal.

UR11 – Information collected within the system will be displayed on a DCO Directory page

4.3 Data Flow

User registration is the first point of data collection. The form provided to the user will allow them to provide the information, including required information as well as other information. The information needs to be stored for later use by the system.

The information collected by the user will be accessible by the DCO User Administrators to determine whether or not to accept the user’s registration request.

Once the DCO User Administrator accepts the request the information is updated in the DCO Single Sign-On system.

DCO User Information Flow Functional Requirements 7

Using the user’s information it will be determined if the user’s profile already exists in the DCO Information Portal. If it does already exist then the existing profile will be updated with the provided information. If it does not already exist then a new profile will be created, creating a new URI to represent the user’s information, and a DCO-ID that gives external sources as well as the components within the DCO System linkage to the user’s information.

The first time the user logs in to the DCO Community Portal the Community Portal will access the user’s information from the DCO SSO system in order to pre-populate the user’s information within the community portal, grant the basic access privileges to the user, and subscribe the user to the DCO Newsletter.

4.4 Logical Data Model/Data Dictionary

4.4.1 Information collected at time of registration from the user by DCO SSO

Given Name

Family name

Username (uid)

Password (encrypted)

Email Address

Additional user information. See Glossary B for all the additional information collected.

4.4.2 Information stored in the DCO SSO System when submitted by the user

User Information from list above plus.

Date and time the account registration was submitted

Status of the request = “requested”

4.4.3 Information stored in the DCO SSO System when confirmed by the user

List in 4.4.2 above plus:

Date and time the account registration was confirmed by the user

Status of the request = “confirmed”

4.4.4 Information stored in the DCO SSO System once request has been acted on

List in 4.4.3 above plus:

Date and time the account registration was accepted/denied on

DCO User Information Flow Functional Requirements 8

Email address of the DCO User Administrator who accepted/denied the request

Status of the request = “accepted” or “denied”

4.4.5 Information stored in the DCO Information Portal

User Information from 4.4.1 list above plus:

URI identifying the user within the system

DCO-ID providing external linkage of the user

4.4.6 Information stored in the DCO Community Portal

Username (uid)

Email Address

Initial portal role of dco_user

4.4.7 Information stored in the DCO Newsletter mailman service

Given Name

Family Name

Email Address

4.5 Functional Requirements

4.5.1 Functional Requirements Group 1 – New UserSection/ Requirement ID Requirement DefinitionFR1 The DCO SSO component shall store all the user’s provided information for

later use by other components of the system.FR2 The DCO SSO component shall store user’s provided information in the

LDAP system to allow the user to login to the various components of the system.

FR3 The DCO SSO component shall add the user to the DCO Newsletter by sending an email to the mailman service.

4.5.2 Functional Requirements Group 2 – DCO User AdministratorSection/ Requirement ID Requirement DefinitionFR4 The DCO SSO component shall provide the DCO User Administrator with

the ability to accept/deny the user’s request.

DCO User Information Flow Functional Requirements 9

FR4.1 The email sent by the DCO SSO component to the DCO User Administrators shall have links to allow the administrator to accept or deny the request

FR4.2 The DCO SSO component shall provide the DCO User Administrator with a web-based page listing all pending requests with links to accept or deny the user’s request.

4.5.3 Functional Requirements Group 3 – DCO Information Portal

Section/ Requirement ID Requirement DefinitionFR5 The DCO Information Portal component shall provide the DCO SSO

component the service to query it’s store to determine if a user already exists.FR6 The DCO Information Portal component shall provide the DCO SSO

component the service to push updated information about the user to the DCO Information Portal.

FR7 The DCO Information Portal component shall provide the DCO SSO component the service to create a new user profile in the DCO Information Portal.

FR8 The DCO Information Portal component shall utilize the DCO SSO component to give access to the user to the DCO Information Portal.

4.5.4 Functional Requirements Group 3 – DCO Community Portal

Section/ Requirement ID Requirement DefinitionFR9 The DCO Community Portal component shall access the DCO SSO

component to retrieve the user’s information the first time the user logs in to the component.

FR10 The DCO Community Portal component shall utilize the DCO SSO component to give access to the user to the component.

FR11 The DCO Community Portal component shall provide a DCO Directory of all DCO Users using the information collected in the DCO Information Portal.

5 OTHER REQUIREMENTS

5.1 Interface Requirements

5.1.1 DCO SSO component interface

The DCO SSO component will be implemented as an extension to the existing RESTful service (LOGIN, LOST USERNAME/PASSWORD, CHANGE PASSWORD, DCO User Admin accept service, DCO User Admin deny service) to provide DCO User

DCO User Information Flow Functional Requirements 10

Administrators with a list of all pending user registration requests. The web page provided will have the same look and feel as all the other DCO SSO web pages. On the web page the administrator will have the ability to individually accept or deny a request, or be able to select one or more requests and take bulk action on those selected.

Any requests and actions taken by administrators will require a validation code. The validation code will be provided when the user requests the request list. The verification code will be a part of the form when submitted so that the administrator does not have to provide it again. The page returned once an action is taken will update the current list of pending requests.

The information stored by the DCO SSO component eventually be supplanted by the information in the DCO Information Portal and no longer valid. For this reason an additional field will be added to the DCO SSO database with the user’s URI.

The DCO SSO component will also add RESTful services to other components of the system so that they may retrieve the original information provided by the user. A verification code will be required by the other components to access the information.

5.1.2 DCO Information Portal interface

The DCO Information Portal can use the existing endpoint, either the VIVO endpoint or the Fuseki endpoint, for other components to query for existing information. For these functional requirements the DCO SSO component will query the system to determine if a user already exists within the system.

The VIVO external API can also be used by other components in the system to add, modify, or delete information.

5.1.3 DCO Community Portal

No additional interfaces need to be provided by Drupal.

5.1.4 DCO Newsletter email list

The list is maintained by a mailman interface. There is a mechanism that will allow a mailman administrator to subscribe a user to the list.

5.1.5 Hardware Interfaces

All components of the system current reside on the deepcarbon.tw.rpi.edu system. No additional interfaces need to be provided by the machine.

5.1.6 Communications Interfaces

The components of the system are behind the RPI Firewall. Ports available outside the firewall are ports 80 and 443. No additional ports are required to be open.

5.2 Data Conversion Requirements

Current information within the DCO Community Portal will need to be migrated to the DCO Information Portal. The information is provided in the following hackpad:

DCO User Information Flow Functional Requirements 11

https://deepcarbon.hackpad.com/aPaSlspuA2m#:h=Where-Info-Is-Currently

5.3 Hardware/Software Requirements

No additional hardware or software components will be required to complete these requirements. Only additional services provided by the components.

5.4 Operational Requirements

5.4.1 Security and Privacy

Password provided by the user must be encrypted within the system. No one, not even DCO User Administrators, will be able to view their password:

A. Consequences of a breach of this security requirement:

1. If the form is only using the http protocol then external systems will be able to sniff for information, gaining access to a user’s uid and password, and attempting to access other systems the user might have access to, including but not limited to financial institutions.

2. Anyone with access to the DCO SSO system will have the ability to use the user’s uid and password to access information about the user or to masquerade as the user.

B. Type of security required:

1. When providing the password the form will be accessible only by https.

2. Password will be stored in the MySQL database using the built-in encryption mechanism.

Verification code required by DCO User Administrators in order to access and act on pending user registration requests.

A. Consequences of a breah of this security requirement:

1. External sources will be able to access the user’s information and act on any user registration requests, potentially including their own registration request.

B. Type of security required:

1. When providing the verification code the service will be accessibly only by https.

2. Verification codes will be encoded and stored in the components properties file.

The Security Section describes the need to control access to the data. This includes controlling who may view and alter application data.

5.4.2 Audit Trail

An audit trail will be required in case questions arise in the future. We may need to know when a particular user requested an account, when an administrator accepted or denied the request, and who accepted or denied the request.

DCO User Information Flow Functional Requirements 12

In addition to DCO User Administrators being able to see a list of all pending requests they will also be able to see any requests that were made but not confirmed, a list of all requests that were accepted or denied and who denied them.

Logging information will be used in all the various components to verify that certain activities were performed. In addition, if any errors occur during the user information flow DCO System Administrators need to be informed if there were any errors or exceptions within the system such as, but not limited to, being unable to reach the DCO SSO system, being unable to reach the DCO Information Portal endpoint and being unable to reach the DCO Information Portal external API for adding or updating user information.

5.4.3 Reliability

A. Component reliability:

1. Damage that can result from failure of this system

a) Loss of information provided by the user

b) Incorrect or invalid information stored in components of the system, which gives external sources incorrect information about the user.

2. The minimum level of reliability for the system is no less 100% except during system maintenance. Maintenance includes, but is not limited to, the hardware being upgraded or rebooted and when system components are upgraded and restarted. When these events happen user’s will be notified and there will be known downtime.

B. Required reliability:

1. System components should be monitored and notifications sent if not available. Though we are a research lab within a polytechnic institute we should be able to respond to such failures within a few hours.

2. If there are failures within the system then we must investigate the cause of the failure to make sure that it does not happen again.

3. If there is a failure in the system we must provide enough information to the community to let them know that there is an issue and that we are working on it.

4. If there is a failure in the system then resources will be immediately assigned in order to quickly and efficiently respond to the failure.

Reliability is the probability that the system processes work correctly and completely without being aborted.

5.4.4 Recoverability

A. In the event the DCO SSO component fails the mysql database will be backed up at regular intervals. Currently that is every 24 hours. No redundancy is currently available.

B. In the event the DCO SSO component fails the LDAP information will be backed up at regular intervals. No redundancy is currently available.

DCO User Information Flow Functional Requirements 13

C. In the event the DCO Information Portal fails the information in the triple store will be backed up at regular intervals. No redundancy is currently available.

D. In the event the DCO Community Portal fails the information in the Drupal database will be backed up at regular intervals. Currently that is every 24 hours. No redundancy is currently available.

Recoverability is the ability to restore function and data in the event of a failure.

5.4.5 System Availability

All components of the system must be available to users 24 hours a day 7 days a week except during regular maintenance. We perform system upgrades and potential reboots once a month, 3rd Tuesday of the month, starting at midnight eastern/10pm mountain.

From time to time we may need to bring down a component of the system in order to upgrade it. These upgrades should take no longer then 1 hours. We should also have a back-out plan in case the upgrade fails. This should limit DCO system downtime.

System availability is the time when the application must be available for use. Required system availability is used in determining when maintenance may be performed.

5.4.6 General Performance

A. Response time for queries and updates: The system should respond in a reasonable amount of time, especially when dealing with a user registering for an account. The user should be notified immediately of any changes in their account request. Though we should expect good response times for DCO User Administrators and DCO System Administrators, it is not as important as response times to the user.

B. Throughput: There is not a great amount of information flowing between the components for user information flow.

C. Expected rate of user activity: We typically see anywhere from 2-6 new user registration requests per week.

5.4.7 Data Retention

User information provided for user registration requests should be retained indefinitely. The exception here is for requests that have not been confirmed for over a certain amount of time.

5.4.8 Error Handling

Any errors that occur within the system must be logged to the corresponding components logging system, and DCO System Administrators must be notified in order to keep information loss to a minimum. DCO System Administrators will then be able to determine if any information is lost, and be able to retrieve the information from the original user information provided.

5.4.9 Validation Rules

User’s username must not already exist in the system (case insensitive).

DCO User Information Flow Functional Requirements 14

User’s email address must be a well-formed email address and must not already exist in the system (case insensitive)

User’s password must be between 6 and 16 characters and must not contain the characters <, >, or &.

Additional information provided by the user, currently the user’s Organization, must not include the characters that are not allowed as values in a JSON object.

The system ensures that no provided information contains data injections.

5.4.10 Conventions/Standards

Information stored in the DCO Information Portal is in the form of RDF Triples and follows the 5-start linked data standards. Any information pushed to that system by DCO SSO will be in said format.

DCO User Information Flow Functional Requirements 15

APPENDIX A - GLOSSARY

DCO – Deep Carbon Observatory

SSO – Single Sign-On, implemented using Shibboleth.

LDAP – Lightweight Directory Access Protocol

VIVO – Application used for the DCO Information Portal

Drupal – Application used for the DCO Community Portal

RPI – Rensselaer Polytechnic Institute, institute from where the DCO Data Science Team operates

TWC – Tetherless World Constellation, DCO Data Science Team members are a part of this group at RPI.

DCO Engagement – A team of DCO Community Members who interact with the different DCO Communities and Groups.

DCO Data Science Team – A team of DCO Community Members who are responsible for providing the DCO Community with Data Management and Data Science services

DCO User Information Flow Functional Requirements 16

APPENDIX B – User Information

Information Label Description Values Required

ORCID User’s orcid id from http://orcid.org/

Text field No

ResearcherID User’s Identification from http://www.researcherid.com/

Test Field No

ScopusID User’s identification from http://www.scopus.com/

Text Field No

DCO Areas of Interest Set of communities and groups that a user might be interested in.

Multi-selection list of communities and groups

No

Title Word used to state position, qualifications, position in organization, sex

Text field for Mr. Mrs. Ms. Prof. Dr., etc…

No

Organization Place the user works or performs research, such as university, federal agency, company, department

Text field with word completion of current set of organizations maintained in the system. URI saved if already exists, label if not

Yes

Organization Country Country in which the persons place of work/research resides

Dropdown of current list of countries, select one

Yes, if organization not selected from list above but entered by user

Organization URL Web address for the user’s place of work/research.

Text field, simple web address verification

Yes, if organization not selected from list above but entered by

DCO User Information Flow Functional Requirements 17

user

Language List of languages that the person speaks

Text field Yes

Home Country Country in which the person lives/works

Dropdown of current list of countries, select one

Yes

Areas of Expertise List science domains / list of expertise (Volcanology, Geochemistry, Science Communications)

Text field with word completion of current set of science domains or list of expertise, URI saved if already exists, label if not

Yes

Telephone Phone number where the person can be reached

Text field No

Skype Skype username for the person

Text field No

Personal URL Web address for the person specifically

Text field, simple web address verification

No

Mailing Address: Institution/Organization

Specific address for the person at their organization, not personal address, should include enough information to be able to send materials

Text Area No

DCO User Information Flow Functional Requirements 18