# Facilio Connected Apps

> Build custom UI components inside the Facilio facility management platform using Vue.js (preferred) or any web technology. Apps run in a secure iframe (web) or webview (mobile) with the Apps SDK providing full access to platform data, real-time events, and SAML-based SSO — no API keys needed.

Key facts:
- SDK CDN (standard): `https://static.facilio.com/apps-sdk/latest/facilio_apps_sdk.min.js`
- SDK CDN (beta — for Revive customers and mobile): `https://static.facilio.com/apps-sdk/beta/facilio_apps_sdk.min.js`
- **For new connected app development, use beta version** — `https://static.facilio.com/apps-sdk/beta/facilio_apps_sdk.min.js`
- Vue.js preferred — init SDK in `created()`, store on `window.facilioApp`
- Wait for `app.loaded` before any API calls
- All date/datetime fields: milliseconds since epoch
- Custom fields: `{fieldName}_{moduleName}` pattern
- Design System: https://dsm.facilio.in
- Apps: Maintenance, Vendor, Requester, Client, Tenant

## Getting Started

- [Overview](https://facilio.com/developers/docs/connected-apps/): Architecture, widget catalog with app/mobile compatibility, SDK quick reference
- [Getting Started](https://facilio.com/developers/docs/connected-apps/getting-started/): Step-by-step tutorial — project setup, hosting, Facilio registration, data access

## Guides

- [Best Practices](https://facilio.com/developers/docs/connected-apps/best-practices/): SDK init patterns, error handling, pagination, server-side filtering, form widget tips, debouncing, security
- [Design & Styling](https://facilio.com/developers/docs/connected-apps/design-system/): Facilio Design System (Storybook at dsm.facilio.in), design principles
- [Exporting Widgets](https://facilio.com/developers/docs/connected-apps/exporting-widgets/): Export as PDF or image via Facilio Script — `exportAsPDF()` and `exportAsImage()` with full options
- [Building with AI Tools](https://facilio.com/developers/docs/connected-apps/ai-tools/): Use the llms-full.txt URL directly with ChatGPT, Claude, Lovable, and Cursor
- [Troubleshooting](https://facilio.com/developers/docs/connected-apps/troubleshooting/): SDK loading issues, blank widgets, silent failures, form events, CORS, and FAQ

## Widget Types

- [Web Tab](https://facilio.com/developers/docs/connected-apps/widgets/webtab/): Full-page tab — all apps, mobile: yes
- [Record Summary Tab](https://facilio.com/developers/docs/connected-apps/widgets/recordSummary/): Tab in record summary — all apps, mobile: yes. Context: `getContext()` returns record directly (use `record = getContext()`, not `ctx.record`). Trigger: `reloadData`
- [Create Record Page](https://facilio.com/developers/docs/connected-apps/widgets/createRecord/): Replaces create form — all apps, mobile: yes. **Single widget per module per account.** Triggers: `save(createRecordResponse)`, `cancel` (cancel button only)
- [Edit Record Page](https://facilio.com/developers/docs/connected-apps/widgets/editRecord/): Replaces edit form — all apps, mobile: yes. **Single widget per module per account.** Context provides record. Triggers: `save(updateRecordResponse)`, `cancel` (cancel button only)
- [Custom Button](https://facilio.com/developers/docs/connected-apps/widgets/custombutton-widget/): Dialog on button click — all apps, mobile: yes. Context: `getContext()` returns record directly. Triggers: `hide`, `resize`, `reloadData`
- [PDF Template](https://facilio.com/developers/docs/connected-apps/widgets/pdf-template/): Custom PDF reports for any module — all apps. Mobile: download only via Custom Button (Open PDF). Context: `template`, `record`, `print`, `download`. Trigger: `updateTemplateSettings`
- [Dashboard Widget](https://facilio.com/developers/docs/connected-apps/widgets/dashboardWidget/): Inside dashboards — all apps, mobile: yes. Event: `db.filters.changed`
- [Topbar](https://facilio.com/developers/docs/connected-apps/widgets/topbar/): Top nav icon + topbar panel — **Maintenance only**, mobile: no. **Single widget per account.** Icon hidden by default — call `setIcon` then `show`. Triggers: `show`, `hide`, `showHeader`, `setUnseenCount`, `setIcon`, `setTitle`, `resize`. Events: `topbar.active/inactive`, `navigation.change` (current app URL when URL changes)
- [Dialer](https://facilio.com/developers/docs/connected-apps/widgets/dialer/): Floating popup — all apps, mobile: no. **Single widget per account** (e.g., cannot add two dialers). Triggers: `open`, `close`, `maximize`, `minimize`, `resize`, `setBadge`, `setTitle`, `setTheme`, `startRinging`, `stopRinging`. Events: `dialer.active/inactive`, `navigation.change` (current app URL when URL changes)
- [Form - Sidebar](https://facilio.com/developers/docs/connected-apps/widgets/form-sidebar/): Right side of form — all apps, mobile: no. Triggers: `setValue`, `getValue`, `getFormData`, `getFormMeta`, `setSubFormData`, `getCurrentRecord`. Events: `form.changed`, `form.{field}.changed`
- [Form - Background](https://facilio.com/developers/docs/connected-apps/widgets/form-background/): Hidden background — all apps, mobile: no. Same triggers/events as Form Sidebar
- [Related List](https://facilio.com/developers/docs/connected-apps/widgets/relatedList/): Related list section — all apps, mobile: yes. Context: `getContext()` returns parent record directly

## JavaScript SDK Reference

- [Installation & Core](https://facilio.com/developers/docs/connected-apps/sdk-reference/installation/): SDK setup, `init()` / `initSync()`, events (`app.loaded`, `app.destroyed`), core methods (`getWidget`, `getContext`, `getCurrentUser`, `getCurrentOrg`, `isExportMode`, `isMobile`)
- [Data API](https://facilio.com/developers/docs/connected-apps/sdk-reference/api/): CRUD operations, uploadFile (10 MB max), field type reference, record object reading (picklist: displayName then name; lookup: name), custom field naming, filter operators, filter examples
- [Request API](https://facilio.com/developers/docs/connected-apps/sdk-reference/request/): `invokeConnectorAPI`, `invokeExternalAPI` (both return string — use `JSON.parse()` for JSON), `invokeFacilioFunction`. Note: `invokeFacilioAPI` is deprecated — use Data API
- [Variables](https://facilio.com/developers/docs/connected-apps/sdk-reference/variables/): Key-value storage — `set` returns variable object, `get` returns value directly (null if missing), `delete` returns true
- [Interface](https://facilio.com/developers/docs/connected-apps/sdk-reference/interface/): `navigateTo`, `openSummary`, `openListView`, `openForm`, `getCurrentPage` (web), `openQRScanner` (mobile), `fullscreen` (web), `trigger`, `notify`, `openURL`, `triggerDownload`
- [Live Events](https://facilio.com/developers/docs/connected-apps/sdk-reference/liveEvent/): `subscribeUserEvent`, `subscribeOrgEvent`, `unsubscribe` — real-time push from Facilio Script
- [Common Utilities](https://facilio.com/developers/docs/connected-apps/sdk-reference/common/): `toBase64({url})` or `toBase64({fileId})` — returns base64 string directly for images (photos, attachments, signatures)

## Optional

- [Facilio API Reference](https://facilio.com/developers/docs/api-reference/): REST API docs
- [Facilio Scripting](https://facilio.com/developers/docs/script-reference/): Server-side scripting for `invokeFacilioFunction()` and export functions