UI Integration Framework

The UI Integration Framework allows developers to extend the Egnyte Web UI by adding custom actions to the "More" menu and context menu for files and folders. This enables users to trigger your app's functionality directly from the Egnyte interface.

Overview

The UI Integration Framework enables you to:

• Add custom menu items to the Egnyte Web UI
• Trigger actions on selected files or folders
• Receive file metadata and OAuth tokens to interact with the Egnyte API
• Configure user-specific settings for your integration

Your integration is defined in a definition.json file that specifies where and how your app appears in the Egnyte UI.

How It Works

Integration Flow

1. User selects files/folders in the Egnyte Web UI
2. User clicks your custom menu item (in "More" or context menu)
3. Egnyte POSTs to your service URL with file metadata and OAuth token
4. Your service responds with a redirect URL
5. Egnyte opens the redirect URL in the user's browser
6. Your app performs actions using the Egnyte API
7. (Optional) Your app notifies Egnyte to refresh the UI

App Definition

The definition.json file defines your app's listing in the Egnyte App Store and configures how custom actions appear in the UI.

Definition Schema

* At least one support contact method (web, email, or phone) is required
** Required depending on type value
*** Required if type is egnyte_ui

Integration Object Schema

Each key in the integrations object defines a separate menu item. The key becomes the default menu text if text is not specified.

Example Definition

{
  "appId": "abccompany",
  "name": "Egnyte for ABC Company",
  "company": {
    "name": "ABC Company, Inc.",
    "website": "https://www.abccompany.com"
  },
  "apiKey": "your_api_key_here",
  "support": {
    "web": "https://example.com/abccompany/helpdesk",
    "email": "support@abccompany.com"
  },
  "categories": ["productivity", "collaboration"],
  "type": "egnyte_ui",
  "appLogo": "https://example.com/abccompany/static/abc_company_logo.png",
  "description": "Send documents for electronic signature using ABC Company.",
  "longDescription": "Send documents from your Egnyte account to ABC Company for signing. Once the e-signature workflow is complete, the signed document is automatically saved back to your Egnyte account.",
  "screenshots": {
    "images": [
      "https://example.com/screenshots/screenshot1.png",
      "https://example.com/screenshots/screenshot2.png",
      "https://example.com/screenshots/screenshot3.png"
    ]
  },
  "userSettings": "https://example.com/abccompany/user/setup",
  "integrations": {
    "sendFiles": {
      "entryPoint": "context_menu",
      "types": ["file"],
      "serviceUrl": "https://example.com/abccompany/files/invoke",
      "extensions": ["pdf", "doc", "docx"],
      "permissionLevels": ["owner", "full", "editor"],
      "invocationMethod": "post_to_tab",
      "icon": "https://example.com/abccompany/static/abccompany_icon.png",
      "text": "Send with ABC Company"
    },
    "sendTemplates": {
      "entryPoint": "more_menu",
      "types": ["folder"],
      "serviceUrl": "https://example.com/abccompany/templates/invoke",
      "permissionLevels": ["owner", "full", "editor"],
      "invocationMethod": "post_to_tab",
      "icon": "https://example.com/abccompany/static/abccompany_icon.png",
      "text": "Send template with ABC Company"
    },
    "viewEnvelopes": {
      "entryPoint": "more_menu",
      "types": ["folder"],
      "serviceUrl": "https://example.com/abccompany/envelopes/invoke",
      "permissionLevels": ["owner", "full", "editor", "viewer"],
      "invocationMethod": "post_to_tab",
      "icon": "list-alt",
      "text": "Check Status of ABC Company Requests"
    }
  }
}

User Settings Flow

The User Settings flow allows you to collect and store user-specific configuration (such as authentication tokens) when a user installs your app. This flow is optional and only triggered if userSettings is defined in definition.json.

Flow Overview

1. User installs your app in Egnyte
2. Egnyte generates a one-time token and opens your userSettings URL
3. Your app collects user settings
4. Your app POSTs settings back to Egnyte's save_url
5. Egnyte stores settings and includes them in future invocations

User Installs Your Application

When a user installs your app, Egnyte opens your userSettings URL in a new browser tab with query parameters.

Request

GET {userSettings}?token={one_time_token}&save_url={save_url}&domain={domain}

Query Parameters

Example Request

curl -i -X GET "https://{redirect_uri_base}/abccompany/user/setup?token={access_token}&save_url=https://{domain}.egnyte.com/pubapi/v1/integrations/save&domain=apidemo.egnyte.com" \
     -H "Host: example.com" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Save User Settings to Egnyte

After collecting user settings, POST them to the save_url provided in the initial request.

Request

POST {save_url}

Request Body

Example Request

curl -i -X POST "https://{domain}.egnyte.com/pubapi/v1/integrations/save" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "token": "abc123xyz",
  "data": {
    "auth_token": "user_oauth_token_here",
    "preferences": {
      "auto_save": true,
      "notification_email": "user@example.com"
    }
  }
}'

Response

200 OK

Egnyte stores the user settings and invalidates the one-time token. The settings in data will be included in the config field of future invocation requests.

Invocation Flow

When a user triggers your custom action, Egnyte initiates a server-to-server POST to your serviceUrl, then opens a redirect URL in the user's browser.

Flow Overview

1. Egnyte POSTs to your serviceUrl with file metadata and OAuth token
2. Your service stores the request and returns a redirect URL
3. Egnyte opens the redirect URL in the user's browser
4. Your app performs actions using the Egnyte API
5. (Optional) Your app notifies Egnyte to refresh the UI

Receive Invocation from Egnyte

When a user clicks your menu item, Egnyte sends a POST request to your serviceUrl.

Request

POST {serviceUrl}

Request Headers

Request Body

userInfo Object

items Array Elements

Example Request

curl -i -X POST "{serviceUrl}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "domain": "https://{domain}.egnyte.com",
  "token": "68zc95e3xv954u6k3hbnma3q",
  "userInfo": {
    "id": 12345,
    "first_name": "Jane",
    "last_name": "Doe",
    "username": "jdoe"
  },
  "items": [
    {
      "checksum": "4f8e628cb324c3176f42a26478fdce624cab17d124b5e80395a05c7b1dba6eb9...",
      "size": 3745,
      "path": "/Shared/Documents/Demo/test.docx",
      "name": "test.docx",
      "locked": false,
      "is_folder": false,
      "entry_id": "{entryId}",
      "group_id": "{groupId}",
      "last_modified": "Fri, 30 Oct 2015 10:28:41 GMT",
      "uploaded_by": "jdoe",
      "num_versions": 1,
      "num_notes": 0
    }
  ],
  "config": {
    "auth_token": "user_oauth_token_here",
    "preferences": {
      "auto_save": true
    }
  }
}'

Return Redirect URL

Your service must respond with a JSON object containing a redirect URL.

Response

200 OK

Example Response

{
  "redirect": "https://example.com/abccompany/session/a1b2c3d4"
}

Example Implementation

from flask import Flask, request, jsonify
import uuid
import redis

app = Flask(__name__)
cache = redis.Redis()

@app.route('/abccompany/files/invoke', methods=['POST'])
def invoke():
    data = request.json
    
    # Generate unique session ID
    session_id = str(uuid.uuid4())
    
    # Store invocation data
    cache.setex(
        f"session:{session_id}",
        3600,  # 1 hour expiry
        json.dumps(data)
    )
    
    # Return redirect URL
    return jsonify({
        "redirect": f"https://example.com/abccompany/session/{session_id}"
    })

Handle User Browser Session

Egnyte opens the redirect URL in a new browser tab. Your app retrieves the stored invocation data and presents your UI to the user.

Example Session Handler

@app.route('/abccompany/session/<session_id>')
def session(session_id):
    # Retrieve stored data
    data = json.loads(cache.get(f"session:{session_id}"))
    
    # Use the OAuth token to interact with Egnyte API
    token = data['token']
    domain = data['domain']
    items = data['items']
    
    # Redirect to main app interface
    return redirect(f"/abccompany/app?session={session_id}")

Notify Egnyte of Changes (Optional)

While your app is open, you can communicate with the Egnyte Web UI using JavaScript events to refresh the file list or notify users of completion or errors.

Use the Egnyte JavaScript SDK to send events:

• Completion: Notify that your action completed successfully
• Error: Display an error message to the user
• Refresh: Reload the file/folder list in Egnyte

Example: Notify Completion

// Include Egnyte JS SDK
import Egnyte from 'egnyte-js-sdk';

// Notify Egnyte that the action completed
Egnyte.uintegrate.notifyCompletion({
  message: "Document sent successfully"
});

Example: Refresh File List

// Trigger a refresh of the current folder
Egnyte.uintegrate.refresh();

Example: Show Error

// Display an error to the user
Egnyte.uintegrate.notifyError({
  message: "Failed to send document. Please try again."
});

Best Practices

Security

• Validate tokens: Always verify that the one-time token in User Settings Flow is valid before saving settings
• Store tokens securely: Encrypt OAuth tokens and user settings in your database
• Use HTTPS: All URLs in definition.json must use HTTPS
• Expire sessions: Set reasonable expiration times for session data (recommended: 1 hour)

User Experience

• Fast redirects: Respond to invocation POSTs quickly (< 2 seconds) to avoid user-facing delays
• Clear menu text: Use concise, action-oriented labels for menu items (e.g., "Send with ABC Company" not "ABC Company Integration")
• Appropriate icons: Use recognizable icons that match your action's purpose
• Handle errors gracefully: Use notifyError to inform users of failures instead of showing generic error pages

API Usage

• Reuse tokens: The OAuth token in invocation requests is valid for the user's session — cache it for the duration of your workflow
• Respect rate limits: Follow Egnyte's rate limits (2 QPS, 1,000 calls/day by default)
• Use entry IDs: Prefer entry_id over path when making API calls, as paths can change

Related Resources

• Egnyte JavaScript SDK — Client-side SDK for interacting with Egnyte
• Public API Authentication — OAuth 2.0 implementation guide
• File System API — API for working with files and folders
• Partner Program — Contact to request UI Integration Framework access