fw-attach

fw-attach is a Freshdesk Platform 3.0 sample for a serverless pipeline: ticket attachment → Object Store → Google Drive using a request template (application/octet-stream with "file": { "ref": ... }). It also uploads to Box with multipart/form-data and platform OAuth, includes optional mock templates for octet-stream and multipart, and completes a Slack external file upload using templates for the Web API steps. Together it is a practical reference for automation and request-template setup.

At runtime the app fans out to Google Drive, Box (multipart), and Slack.

1. Install – onAppInstall requires Freshdesk subdomain and API key; completes with renderData() or blocks with renderData({ message }) (≤60 characters).
2. Staging – On onConversationCreate, download a ticket attachment (Freshdesk attachment URLs are dynamic), upload to Object Store, pass fileRef into templates.
3. Google Drive – uploadFileToGoogleDrive uses platform OAuth (config/oauth_config.json, integration google_drive) and <%= access_token %> — no manual token refresh in code.
4. Box – uploadFileToBox uses platform OAuth (box in config/oauth_config.json), multipart/form-data with attributes (JSON: name + parent folder) before file per Box upload API, and Object Store fileRef on formData.files.file.
5. Slack – slackGetUploadURLExternal and slackCompleteUploadExternal use $request.invokeTemplate; the middle step uploads bytes to the host-specific upload_url Slack returns from files.getUploadURLExternal.

Serverless logic: server/server.js.

---

Optional request mocks

Turn on enable_octet_mock or enable_multipart_mock in install parameters to hit mock hosts defined in config/requests.json and exercise the octet-stream and multipart template shapes without real third-party calls.

---

Google Cloud setup

1. Google Cloud Console → enable Google Drive API.
2. Credentials → OAuth client ID (Web application). Add authorized redirect URI: https://oauth.freshdev.io/auth/callback (and http://localhost:10001/auth/callback for local FDK).
3. OAuth consent screen – scope https://www.googleapis.com/auth/drive.file.
4. At install, complete Connect for Google Drive in the app settings UI (uses oauth_config.json). Client ID and secret are collected via oauth_iparams — not plain iparams.json.

---

Box Developer Console setup

Yes — you need a Box custom OAuth app in the Box Developer Console (Developer → My Apps → Create new app → User Authentication (OAuth 2.0) or equivalent).

1. Redirect URIs – add https://oauth.freshdev.io/auth/callback and http://localhost:10001/auth/callback (local FDK), same pattern as Google.
2. Application scopes – under Configuration → Application scopes, enable Read all files and folders and Write all files and folders (OAuth equivalents: root_readonly + root_readwrite). config/oauth_config.json sets options.scope to root_readonly root_readwrite so the authorize URL explicitly requests both (matches the two checkboxes; reconnect after changing scopes — see Box scopes).
3. Copy Client ID and Client Secret into install-time Box OAuth fields.
4. Set box_parent_folder_id in iparams to a numeric folder ID (0 = user’s “All Files” root). Prefer a dedicated folder ID if root uploads are restricted for your account. Leave empty to skip Box uploads.

Box 403 access_denied_insufficient_permissions

Box checks both the app’s scopes and the Box user’s ability to do the same action in the web UI (Box support).

1. Re-authorize after scope or options.scope changes – Disconnect Box in the app settings and Connect again so Box issues a new token that includes root_readonly and root_readwrite (old tokens stay limited until re-consent).
2. Folder role (very common) – Box evaluates the user’s permission on the parent folder, not only app scopes. If box_parent_folder_id points at a shared folder where that user is Viewer / preview-only, uploads return access_denied_insufficient_permissions even when the app has Write all files. Use a folder where the authorizing user is Editor or Uploader (or Co-owner), or a folder they own. Confirm by uploading the same file into that folder in the Box web UI as that user.
3. Avoid root (0) when testing enterprise accounts – Some org policies restrict root uploads; create Freshdesk uploads (or similar) in Box, note the folder ID from the URL, set box_parent_folder_id to that ID.
4. Enterprise allowlisting – Org admins may need to allow the custom app (third-party / Platform apps settings) before OAuth tokens can access content.
5. Server/JWT apps – If you ever switch app type, admins must re-approve scopes under Admin Console → Integrations → Platform Apps Manager.

---

Product support & limitations

Topic	Notes
Freshdesk	Serverless onConversationCreate; Object Store + templates for Drive / Box / Slack.
Object Store allowlist	PNG, JPEG, CSV, JSON, XLS(X) in this sample.
Drive upload	Simple media upload (uploadType=media) via template.
Box upload	Multipart attributes + file to upload.box.com (≤50 MB per Box; larger files need chunk upload APIs).

---

Prerequisites

1. Freshdesk subdomain + API key.
2. Google – OAuth app + install-time authorization for Drive.
3. Box (optional) – OAuth app + folder ID; connect Box at install.
4. Slack – Bot token (files:write), channel ID. See Uploading files.

---

Run locally

cd fw-attach
fdk run

Use the serverless simulator to exercise onAppInstall and onConversationCreate.

---

Files

Path	Purpose
config/oauth_config.json	Google Drive (google_drive) + Box (box) OAuth
config/requests.json	Drive + Box multipart + Slack Web API + optional mocks
config/iparams.json	Freshdesk + Slack + mock toggles
manifest.json	onAppInstall, common.requests, support_ticket events
server/server.js	Handlers + helpers after exports

---

Security

• Do not log API keys, OAuth secrets, or tokens.
• Prefer platform OAuth over pasted access tokens.