Skip to main content

Approval Workflow User Guide

Overview​

DataCovey's approval workflow system ensures secure and controlled access to projects and datasets across different organizations. This system requires approval from Organization Administrators before cross-tenant associations can be established.

Key Concepts​

Approval Types​

  1. Project-Tenant Association: Inviting another organization to join a project
  2. Project-Dataset Association: Adding a dataset to a project (may require approval if cross-tenant)

User Roles​

  • Organization Administrator (Org Admin): Can approve/reject requests and access admin features
  • Dataset Editor: Can create approval requests for dataset associations
  • Dataset User: Can create approval requests for dataset associations

Approval Process​

  1. Request Creation: User creates an approval request
  2. Email Notification: Org admins receive email notifications
  3. Review: Org admins review the request in the admin panel
  4. Decision: Approve or reject with optional reason
  5. Notification: Requester receives email about the decision
  6. Expiration: Requests expire after 15 days if not acted upon

For Organization Administrators​

Accessing the Admin Panel​

  1. Log into DataCovey
  2. Look for the "Org Admin" item in the navigation menu (only visible to Org admins)
  3. Click to access the admin panel

Managing Approvals​

Viewing Pending Approvals​

  1. Navigate to the "Pending Approvals" tab
  2. Review the list of pending requests
  3. Each request shows:
    • Type of association requested
    • Requester information
    • Project and target details
    • Creation and expiration dates

Approving Requests​

  1. Click on a pending approval request
  2. Review the details in the dialog
  3. Click "Approve" to grant the request
  4. The association will be created immediately
  5. The requester will receive an email notification

Rejecting Requests​

  1. Click on a pending approval request
  2. Optionally provide a rejection reason
  3. Click "Reject" to deny the request
  4. The requester will receive an email notification with the reason

Finding Your Tenant ID​

  1. Navigate to the "Tenant Information" tab
  2. Your Tenant ID is displayed prominently
  3. Use the copy button to copy the ID
  4. Share this ID with external partners who want to invite your organization

Security Best Practices​

  • Only share your Tenant ID with trusted organizations
  • Review all requests carefully before approving
  • Provide clear rejection reasons when denying requests
  • Monitor the admin panel regularly for new requests

For Regular Users​

Requesting Project-Tenant Associations​

  1. Navigate to the project you want to invite another organization to
  2. Click "Invite Tenant to Project" (Org Admin only)
  3. Enter the Tenant ID of the organization you want to invite
  4. Click "Send Invitation"
  5. The organization's admins will receive email notifications

Requesting Project-Dataset Associations​

  1. Navigate to the dataset you want to add to another project
  2. Click "Add Dataset to Another Project" (Org Admin only)
  3. Search and select the target project
  4. Review the project details
  5. Click "Request Association"
  6. If the project belongs to a different organization, approval will be required

Understanding Project Display​

Projects now show additional information:

  • Project ID: Last 7 digits shown in parentheses with monospace font
  • External Badge: Projects from other organizations show an "External" badge
  • Consistent Formatting: All project names follow the format: "Project Name (1234567) [External]"

Email Notifications​

For Approvers​

You will receive emails when:

  • A new approval request is created
  • The email includes:
    • Request details
    • Requester information
    • Direct link to review the request
    • Expiration information

For Requesters​

You will receive emails when:

  • Your request is approved
  • Your request is rejected (with reason if provided)
  • The email includes:
    • Decision details
    • Reviewer information
    • Next steps (if approved)

Approval Expiration​

  • All approval requests expire after 15 days
  • Expired requests cannot be approved or rejected
  • A new request must be created if needed
  • The system automatically processes expirations hourly

Troubleshooting​

Common Issues​

"You must be an Organization Administrator"

  • Only Org admins can access approval features
  • Contact your system administrator to request Org admin role

"Project must be associated with the dataset's tenant"

  • For cross-tenant dataset associations, the project must first be associated with the dataset's tenant
  • Request a project-tenant association first

"A pending approval request already exists"

  • There's already a pending request for this association
  • Wait for the existing request to be processed or expired

"Association already exists"

  • The requested association is already in place
  • Check your project or dataset associations

Getting Help​

  • Contact your Organization Administrator for approval-related questions
  • Check the admin panel for pending requests
  • Review email notifications for request status updates

Best Practices​

For Organization Administrators​

  1. Regular Monitoring: Check the admin panel regularly for new requests
  2. Timely Responses: Respond to requests promptly to avoid expiration
  3. Clear Communication: Provide clear reasons when rejecting requests
  4. Security Awareness: Only approve requests from trusted sources
  5. Documentation: Keep records of approved/rejected requests for audit purposes

For Requesters​

  1. Provide Context: Include clear descriptions when creating requests
  2. Follow Up: Monitor email notifications for request status
  3. Respect Decisions: Accept rejections gracefully and address any concerns
  4. Plan Ahead: Submit requests well before deadlines to allow for approval time
  5. Communication: Coordinate with external partners before creating requests

Technical Details​

System Architecture​

  • Database: PostgreSQL with approval tables
  • Email Service: Mailgun for notifications
  • Scheduler: Google Cloud Scheduler for expiration processing
  • Authentication: JWT-based with role-based access control

Security Features​

  • Role-based Access: Only Org admins can approve requests
  • Tenant Isolation: Users can only see requests for their organization
  • Audit Trail: All approval actions are logged
  • Expiration: Automatic cleanup of old requests
  • Email Verification: All notifications include verification details

API Endpoints​

  • POST /api/v1/approval/project-tenant - Create project-tenant request
  • POST /api/v1/approval/project-dataset - Create project-dataset request
  • GET /api/v1/approval/pending - List pending approvals (Org admin only)
  • POST /api/v1/approval/{id}/approve - Approve request (Org admin only)
  • POST /api/v1/approval/{id}/reject - Reject request (Org admin only)

Support​

For technical support or questions about the approval workflow:

  1. Check this documentation first
  2. Contact your Organization Administrator
  3. Review system logs for technical issues
  4. Submit a support ticket with detailed information

Last updated: [Current Date] Version: 1.0