Access Request Workflow Requirements

Project Title	Access Request Workflow
Target Release
Epic
Document Status	DRAFT
Document Owner	Diana Antova
Document Sign-Off
Subject Matter Expert(s)
Technical Expert(s)	Ian Lessing (Unlicensed), Steven Maglio

Background & Business Value

We need a workflow to allow developers on campus to request access for APIs that require approval before usage. This is a common use case.

Goals

Store information about user applications - contact information and other general information. Have a record of the approval to use APIs for a specific application.

Assumptions

The approval of APIs will be done by business users in most cases, such as the Registrar office.
Other approvals might be done by technical managers at ETS, ARIT, etc.
API and API product are used interchangeably in this document. Developers can request access only to API products.
Roles:
- API Admin - a user role in the portal that gives elevated access to manage the API and Application contents.
- Business Approver - a user role in the portal that allows users to approve publishing and application access requests.
- Developer - a use role in the portal assigned to every person creating an application and requesting access to API products.
- Gateway Admin - a person that has admin rights in the Apigee gateway.
- All gateway admins are also API admins in the developer portal.
- Developer portal: developer.ucsb.edu

Out of Scope

Requirements

Title	User Story	Priority	Notes
Requests API access.	As a Developer, I need a way to request access to APIs for my Apps.	MUST HAVE	This functionality is provided by the developer portal. After a user creates an application, they can request access to API(s) by selecting the API link initially, or by selecting Edit <API name> to add more APIs.
Notify developers on API approval	As a developer I would like to receive notification on API approval for automatic and for manual approvals.	MUST HAVE	Public APIs are approved automatically. Other APIs are approved at a later time and the user is not notified by the system. Requesting access to APIs that require approval put the application in Pending mode.
Notify developer on the process to get access	The system should notify the developer in an email of the process to follow after they submit a request to use APis that require access.	MUST HAVE	The monitoring service sends an email that an application has requested access to an API (that isn't auto-approved). It happens at 1 am. Add a notification to the developer as well with a link on how to request access. How to do?
System display a link to documentation on how to submit access request form	The system should display a link to documentation on how to submit an access request form.	NICE TO HAVE	In addition to an email, the website should have a link to the steps to follow to submit access request. Display either on the Keys tab, or APIs tab
Submit access approval documentation	As a developer I need to submit required documentation to have my API access approved.	MUST HAVE	Current process Fill in a word document and email it to a person in the registrar office. Box link to the word document: https://ucsb.box.com/s/bm6y5dy68ng1pof8e6z804e4oj8vil2e A problem is that the approval is in email only. Box folder is not available to the entire campus, so a person has to email them the document. Proposed: Developer submits a form (content) in Drupal that starts the workflow process. The form will contain the fields in the word document linked above. The form will include the submitting developer contact information. The developer will not fill in the gateway admin, or business approver. These will be filled in by the gateway admin after submission. The form will include the list of API products requested. An email to support@developer.ucsb.edu will be generated as a first step in the workflow. A Gateway Admin will assign the document to themselves and fill in the gateway admin and business approver contacts.
Business approver to approve or deny API access	As a business owner of the data and an API approver I want to be notified of a pending approval. I want to review the information submitted, contact the developer if I have questions, request changes, and record my API approval or denial.	MUST HAVE	People in the Business Approver role can perform this action. The business approver listed in the form is notified of a pending request via email. Email is sent to a personal email and to a generic email account. Email includes a link to the form in the portal, a contact information for the request (developer), and the assigned gateway admin. Business approver logs into Apigee and approves or denies the request. Business approver can go back and forth with the developer to get additional information and to request that certain APIs are added or removed from the Application. Business approver sets the step in the workflow to move it to the next step.
Admins to receive notification of a new API request form submission	Once a developer submits the form request, an email will be sent to support@developer.ucsb.edu. One of the API administrators will fill in the gateway administrator and a business approver in the form.	MUST HAVE	People in the API Administrator role can perform this action. API admins receive an email once a day of a new API request that needs approval. This is done with the scheduled job at 1am and it is sent to support@developer.ucsb.edu. API Admin can get the business approver email and generic email account from a list of APIs.
Gateway admin to approve or deny API access	After the business approver approves the API product access, the gateway admin is notified to review the request and approve the API product request.	MUST HAVE	API Admin reviews the data in the form. API Admin makes sure that the list of APIs that were approved in the form is the same as the list of APIs requested in the application. API admin grants access to the requested APIs.
Provide easy access to application contact info and other information	As a developer, business approver and API admin and gateway admin I would like to see a list of applications and get contact information and other.	MUST HAVE	create a page that lists all application requests and approvals. Make the page available to business approvers and API admins. Make the documents visible to their owners. How will it work with the teams feature? Can the entire team see a document that a teammate has submitted?
Allow for access request to APis approved by different departments.	As a developer I want to make one request for all APIs needed, regardless of who the approving department is. As an API approver I would like to have a way to approve API requests even if there are multiple approvers involved.	MUST HAVE	Allow for multiple business apprvers to approve the APi access request, in case the APIs are provided by multiple departments and require separate approval. Gateway admin can facilitate these by setting the workflow in the appropriate state. Can add additional fields for additional business approvers, or GA can email them.

User Interaction, Design & Architecture

The workflow we want
- Developer (End User)
  1. Create an Account on https://developer.ucsb.edu
  2. Create an App on https://developer.ucsb.edu
    - When creating an app, click on the APIs I would like to use
    - TODO: We should update the API Request Page (My Apps) in Drupal to include text (between the App Name/CallBack Url and the API Product list) with text that states for any API that has "Access Approval Required" next to it will need to have an API Access Request Workflow filled out. There should be a link to the documentation on how to fill the workflow out.
      - Make a Jira ticket out of this
- Gateway Admin
  - 3. The monitoring service sends an email that an application has requested access to an API (that isn't auto-approved)
    - The monitoring service should also send an email to the requesting developer to inform them that they will need to fill out the API Access Request Workflow with a link to the documentation on how to fill the workflow out.
- Developer (End User)
  - 4. Fills out the API Access Request Workflow Form on https://developer.ucsb.edu and submits it
    - Submission should email support@sa.ucsb.edu that a new API Access Request Workflow was filled out
- Gateway Admin
  - 5.

Examples and References

Current Workflow (as of 03 Aug 2018)
- Developer (End User)
  1. Create an Account on https://developer.ucsb.edu
  2. Create an App on https://developer.ucsb.edu
    - When creating an app, click on the APIs I would like to use
- Gateway Admin
  - 3. The monitoring service send an email that an application has requested access to an API (that isn't auto-approved)
  - 4. The Gateway Admin then emails the Developer with an Access Request Form and explain what information they need to have. Documentation on the document and what we need from the developer should be implemented with APIGEE-120.
    - The Gateway Admin includes who (the business approvers) should be emailed by the Developer; which a note to CC the Gateway Admins for awareness.
- Developer (End User)
  - 5. Works with their department staff to fill in the form and get signatures required.
  - 6. Send the Request Form and any additional information to the Business Approvers (with Gateway Admins CC'ed) through email
    - The Gateway Admin will save the initial request document in the box storage area.
- Business Approvers
  - 5. Receives the Request Form, do their internal review, and complete a feedback loop with the Developer (End Users).
  - 6. Upon Approval or Denial, they send and email to the Developers (End Users) and the Gateway Admins.
- Gateway Admin
  - 7. Upon Approval
    - The Gateway Admin then Grants access to the App for the API
    - The Gateway Admin will save the finalized document in the box storage area with "- APPROVED" appended to the filename.
  - 7a. Upon Denial
    - The Gateway Admin then Denies access to the App for the API
    - The Gateway Admin will save the finalized document in the box storage area with "- DENIED" appended to the filename.

Questions

Below is a list of questions to be addressed as a result of this requirements document:

Question	Outcome	Decision Date