# Understanding Quable Apps

By

The Quable Team

A Quable App is like a bridge that connects your Quable PIM (Product Information Management) system with additional functionalities and enhanced user experiences. While traditional integrations and connectors focus on data exchange behind the scenes, Quable Apps bring interactive features directly into your PIM interface.

Quable Apps use a concept called "slots" – designated spaces within the PIM interface where your app can display content and enable user interactions.

There are two ways your app can interact with documents:

1. Single Document Action (document.action.single)

   • Adds a dedicated button to individual document pages
   • When clicked, can either:
     • Perform an immediate action
     • Open an interactive dialog box within the PIM
   • Perfect for document-specific operations like sending to review or generating reports

2. Bulk Document Action (document.action.bulk)

   • Enables actions on multiple documents selected through search
   • Ideal for batch operations like mass updates or exports

1. Side Panel Tab (document.page.tab)

   • Creates a new section in the right-hand column of document pages
   • Excellent for displaying related information or quick-access tools
   • Examples: Preview generators, validation status, external references

2. Full Document Tab (document.page.column)

   • Adds an entirely new tab to the document view
   • Provides maximum space for complex interfaces
   • Perfect for rich features like:
     • Advanced editors
     • Detailed analytics
     • Comprehensive validation interfaces

The same powerful integration capabilities extend to other core PIM objects:

• Variants
• Classifications
• Assets

Each of these objects supports similar slot types, allowing you to create consistent, integrated experiences throughout the PIM.

Quable Apps represent a modern approach to PIM enhancement:

• They provide immediate value to users by being directly accessible in their workflow
• They maintain the familiar PIM interface while adding new capabilities
• They enable real-time interaction rather than background processing
• They can be designed to match your specific business needs

Whether you're looking to streamline workflows, add validation steps, or integrate with external services, Quable Apps provide a framework that puts the user experience first while maintaining the robust integration capabilities you need.

This part of the documentation provides an in-depth understanding of how the PIM interacts with your Quable App implementation.
We'll cover the complete installation process, examine API exchanges between the PIM and your application, and guide you through various user experience possibilities.

Before diving into technical implementation, consider:

• What type of user experience would benefit your team most?
• Which integration points (slots) align with your users' workflow?
• What level of interaction do your users need?

The answers to these questions will guide you in creating a Quable App that not only serves its technical purpose but also provides a seamless, intuitive experience for your users.

Based on your profile, there are two main Application use cases:

• Add custom user experience to your PIM (business-specific application installed through administration)
• Develop applications for multiple instances (using instance administration or headless API approach)

• Contribute to the Quable App Store for all Quable clients
• Requires partner portal usage
• Recommended to master standard installation before exploring the portal

All calls from Quable PIM to QuableApp include these headers:

• Client-ID: Quable
• Referer: {instanceCode} (contains the instance code referencing the QuableApp)

Note: For standalone / custom applications, Quable does not trigger app management calls.

sequenceDiagram
    participant Q as Quable PIM Instance
    participant A as Your Quable App

    rect rgb(240, 240, 240)
        Note over Q,A: Installation flow
        Q->>+A: POST /permission
        A-->>-Q: 200 OK with ["read_access"] or ["full_access"]
        
        Q->>+A: POST /install
        A-->>-Q: 200 OK
    end

    rect rgb(240, 240, 240)
        Note over Q,A: Configuration screen
        Q->>+A: POST /configs
        A-->>-Q: 200 OK (HTML returned)
    end

    rect rgb(240, 240, 240)
        Note over Q,A: Slot usage
        Q->>+A: POST /slot
        A-->>-Q: 200 OK (HTML or JSON depending on slot)
    end

When a user clicks on "Install", the Quable PIM will call:

POST {app-url}/permission

• HTTP Code: 200 OK
• Body:

["full_access"]

or

["read_access"]

This defines whether your app requires read-only or full access to PIM data.

If the user confirms, the PIM sends:

POST {app-url}/install

• HTTP Code: 200 OK

At this step, your app may execute any custom installation logic, such as:

• Creating webhooks
• Adding attributes or custom entities
• Saving credentials
• Initializing external services

Once this call succeeds, the app is officially installed for that customer instance.

When a user accesses your app's configuration screen from the PIM, the following call is made:

POST {app-url}/configs

• HTTP Code: 200 OK
• Body: Valid HTML (your app controls the full display)

This HTML will be embedded in an iframe inside the PIM interface. You are free to design forms, settings, buttons, or navigation.

Your app can enhance the Quable UI by responding to slots (e.g., document tabs, action buttons).

When a user clicks on a configured slot, the PIM sends:

POST {app-url}/slot

{
  "object": {
    "type": "product",
    "ids": ["PROD1", "PROD2"]
  },
  "instance": "customer-instance-id",
  "user": {
    "name": "john.doe",
    "idd": 42,
    "email": "john.doe@example.com",
    "type": "admin",
    "admin": true,
    "permissionFeatures": []
  },
  "slot": "document.action.single",
  "locale": {
    "data": "fr-FR",
    "interface": "en_US"
  }
}

• HTTP Code: 200 OK
• Body: HTML or JSON depending on slot type

This response will be displayed inside a slot-rendering area (iframe-based).

• All endpoints (/permission, /install, /configs, /slot) must be publicly accessible and served over HTTPS.
• Consider authenticating incoming requests (using HMAC).
• Handle errors gracefully and return relevant HTTP codes (400, 500, etc.).
• Log installation events to track per-instance activation.
• Version your endpoints if needed (/v1/install).

1. Navigate to Administration > Quable App
2. Click "New Quable app"
3. Complete the form
4. Enable
5. Activate

Installing or updating an App via API follows the same process as the interface. Refer to the Postman documentation:

• POST a new app
• PUT an existing app

Can be configured during installation or by editing the app in the PIM.

Using the document_tab slot:

sequenceDiagram
    participant B as Browser
    participant Q as Quable PIM
    participant A as App X

    Note over B,A: Document Page Display Process
    
    B->>+Q: Display document page
    
    Q->>+A: POST /slots/document_tab
    Note right of A: Request contains:<br/>- app code<br/>- object type<br/>- object ids
    
    A-->>-Q: Response 2xx<br/>{url: "app-specific-url"}
    
    Q-->>-B: Return URL for tab content
    
    Note over B: Enhances PIM interface<br/>with app content

POST /slots/document_tab?date=YYYMMDDTHHMMSS.XXX&hmac=... HTTP/1.1
Host: {{appUrl}}
Client-Id: Quable
Referer: {{instanceCode}}
Content-Type: application/json

Request body:

{
    "slug": "{{app-code}}",
    "slots": [...],
    "object": {
	    "type" : "document",
	    "ids" : ["{{id}}"]
    },
    "documentType": {
        "id": "{{app-document-type-id}}"
    },
    "name": {...},
    "description": {..},
    "parameters": {
        "keyValues": [...]
    },
    "icon": {...},
    "url": "{{appUrl}}",
    "permissionFeatures": [...],
    "security" : {
        "appSecret" : "efyhlqzfd4g6f4g3s54g3s54g3f5r4gs354g3s5re4g3fdg435xd4ge0q36f47rse3rg7c13sr7g36s7rcg3se"
    }
}

Expected response:

• HTTP Status: 2xx
• Body must contain URL for content display