• Register

UI Integration Framework

The UI Integration Framework enables app developers to hook into the Egnyte Web UI to expose custom actions for their app. Currently, you can extend actions that can be performed on selected item(s) in the "More" menu and the Context menu. To get started with the UI Integration Framework, please contact partners@egnyte.com.

App Definition

The definition.json file defines the listing for your app for our apps page and instructs Egnyte on how custom actions should be exposed in our UI.

Definition Examples

{
    "appId": <GUID>,
    "domains": [<list of domains to restrict this integration to>]
    "name": <app name>,
    "apiKey": <public API key>,
    "company": {
        "name": <company name>,
        "website": <company website> (optional)
    },
    "support": { // at least a web or email value is required
        "web": <support website> (optional),
        "email": <support email address> (optional),
        "phone": <support phone number>  (optional)
    },
    "userManual": <url to user manual> (optional),
    "categories": [<suggested set of categories, subset of ["productivity", "collaboration", "businessAutomation", "securityAdministration", "projectManagement", "migrationSynchronization"]],
    "industries": [<suggested set of industries, options are TBD>],
    "type": "egnyte_ui|web|mobile|desktop", // external = link to external website
    "userSettings": <url to index of the userSettings static js app (optional)>, // called by openSettings method in uintegrate
    "globalSettings": <url to index of the globalSettings static js app (optional)>,
    "description": <short description for appstore>,
    "longDescription": <long description for appstore> (optional),
    "appLogo": <url to app logo image, visible in the appstore, white or transparent background, no padding, preferred up to 236 x 126 px>,
    "invocationAppLogo": <url to app logo image, visible in invocation loading screen, white or transparent background, no size/shape restrictions, defaults to appLogo value> (optional),
    "version": text (optional),
    "screenshots" : {
        "video": [<array with a YouTube video url, preferred 16:9 ratio>] (max 1, optional),
        "images": [<array of image urls, preferred 16:9 ratio, preferred at least 425 x 239 px>] (3+ required, videos can count towards this number)
    },
    "url": <url to app>, // only for links/downloadable apps
    "supportedPlatforms": ["windows|mac|linux|ios|android|wp"], // only for type !== (web|egnyte_ui)  
    "integrations": { // only required for "type" === "egnyte_ui"
        "someId": {
            "entryPoint": <context_menu | more_menu> (one for each integration)
            "allowedPaths": [<restrict the integration to these file system paths>,...] (simple glob string starting from root, optional), //the glob syntax is simplified to only allow * as a special character
            "permissionLevels": [<restrict the integration to these permission levels> (optional)],
            "types": ["file","folder"],
            "extensions": ["xls","xlsx"] (optional),
            "accessLevel": <selection | folder | fileSystem> (optional),
            "serviceUrl": <url of a custom remote service or static app>,
            "invocationMethod": <post_to_tab | post_headless(limited support) | get_to_modal(limited support)>,
            "icon": <icon name from fontawesome 3.2 OR icon image url (14 x 14 px, solid color #626364, transparent background)> (optional),
            "selectionQuantity": <"single" | "multiple" | [2,5]>, //default: not defined == always
            "text": "text to show as menu option if applicable" (optional, defaults to someId value),
            "tooltip": "tooltip text" (optional)
        },
        {... optionally more integrations ...}
    }
}
{
  "appId": "abccompany",
  "name": "Egnyte for ABC Company",
  "company": {
    "name": "ABC Company, Inc."
  },
  "apiKey": ***,
  "support": {
    "web": "https://example.com/abccompany/helpdesk"
  },
  "categories": ["productivity", "collaboration"],
  "type": "web",
  "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": []
},
"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://integrations-staging.example.com/abccompany/static/abccompany_icon.png",
      "text": "Send with ABC Company"
  },
  "sendTemplates": {
    "entryPoint": "more_menu",
    "types": [
      "folder"
    ],
    "serviceUrl": "https://integrations-staging.example.com/abccompany/templates/invoke",
    "permissionLevels": [
      "owner",
      "full",
      "editor"
    ],
    "invocationMethod": "post_to_tab",
    "icon": "https://integrations-staging.example.com/abccompany/static/docusign_icon.png",
    "text": "Send template with ABC Company"
  },
  "viewEnvelopes": {
    "entryPoint": "more_menu",
    "types": [
      "folder"
    ],
    "serviceUrl": "https://integrations-staging.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 occurs when a user installs the integration app. This flow is optional and only triggered if the userSettings Url is set in the definition.json. Generally, this flow is utilized to save a user's authentication token. In definition.json, there is a field called userSettings that points to your application's Url for setup. Egnyte generates a one-time use token and opens that page in a browser. Your application gets the user settings it needs during this time. Egnyte saves the user settings data and sends these back with every invocation.

  1. User Installs Your Application
  2. Your Application Sends User Settings to Egnyte
  3. Egnyte Stores User Settings

1. User Installs Your Application

When a user clicks to install your application, Egnyte produces a one-time use token, T, and opens the userSettings Url (defined in definition.json) in a new tab with the token appended to the Url.

GETuserSettings
Request Example
GET abccompany/user/setup?token=T&save_url=saveUrl&domain=acme.egnyte.com HTTP/1.1
Host: example.com

2. Your Application Sends User Settings to Egnyte

Your application handles the GET request and lets the user provide his settings for your application. Your application sends a POST request to saveUrl with a JSON body that includes the token and data containing the user settings. The POST request confirms the set up was successful.

POSTsaveUrl
Request Body
{
  "token": T,
  "data": {
    <key:value map of user settings>
  }
}

3. Egnyte Stores User Settings

Egnyte stores the data as the user settings for the current user for your application. Egnyte invalidates the one-time use token.

Invocation Flow

1. POST From Egnyte to Your Application

When a user clicks on a button you've exposed, the Egnyte server will send a POST request to your application's server with information that will inform you about the items that were selected and enable you to access the Public API to work on those items.

Your server must respond with a redirect Url that Egnyte will open in the user's browser.

Examples

Headers:
{
  'content-type': 'application/json',
  'user-agent': 'Java/1.7.0_71',
  host: 'integrations-staging.egnyte.com',
  accept: 'text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2',
  'content-length': '623' 
}

Query params:
{} 

Body:
{
  domain: 'https://apidemo.egnyte.com',
  token: '***',
  userInfo: {
    id: 1,
    first_name: 'First',
    last_name: 'Last',
    username: 'username'
  },
  items: [
    {
      checksum: '4f8e628cb324c3176f42a26478fdce624cab17d124b5e80395a05c7b1dba6eb94bd34866a2d147fbee93ac58745d0487f4cf0283da91fa431e5e73dfe555435d',
      size: 3745,
      path: '/Shared/Documents/Demo/test.docx',
      name: 'test.docx',
      locked: false,
      is_folder: false,
      entry_id: 'b986a972-aff8-470e-b9d4-5db0ed8cda15',
      group_id: 'c2377629-bf05-456f-b8c6-6c55c90dd022',
      last_modified: 'Fri, 30 Oct 2015 10:28:41 GMT',
      uploaded_by: 'user1',
      num_versions: 1,
      num_notes: 0
    }
  ],
  config: <settings saved via User Settings Flow>
}

2. Your Application Stores Request

Your application stores the information from the request and returns a JSON object with the Url. This Url typically has a unique identifier for this request.

{
  "redirect": "BrowserFacingUrl"
}

3. Redirect Url Opens in User's Browser

Egnyte opens the redirect Url in a new tab in the user's browser window. The Url can be used to access the information about the selected items and the user's OAuth token.

Your application directs the user to a final Url. We recommend that your application chooses to use a HTTP 302 redirect to display a "pretty" Url to the user.

4. Notify Egnyte of Changes (Optional)

The user session is now established and the user can utilize Egnyte with the integration features. While the app is open, your application can communicate with Egnyte's Web UI using three events: completion, error, and refresh the page. For more information on sending events, please refer to this section of the JavaScript SDK.