# Understanding Quable Apps

By
The Quable Team

# Soon ?

We are working hard right now to deploy this new version of QuableApp.
Stay tuned or ask the support to give you more information when this version will be available (Q1 2025)

# What is a Quable App?

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.

Think of it as adding new rooms to your house rather than just upgrading the plumbing – you're creating new spaces where users can work and interact with your products in ways that weren't possible before.

# How Do Quable Apps Transform Your PIM Experience?

# Interactive Integration Through "Slots"

Quable Apps use a concept called "slots" – designated spaces within the PIM interface where your app can display content and enable user interactions. Imagine these slots as specialized windows where your app can showcase its capabilities exactly where users need them.

# Available Integration Points

# Document Actions

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

# Document Page Enhancements

  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

# Beyond Documents

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.

# Why Choose a Quable App?

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.

# Getting Started

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.

# Stand-alone or AppStore application

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

# Stand-alone Application

  • 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)

# AppStore Application

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

# API Integration

# HTTP Headers

All calls from Quable PIM to QuableApp include these headers:

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

# API Lifecycle Calls

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

sequenceDiagram
    participant Q as Quable PIM Instance
    participant A as Your QuableApp
    
    rect rgb(240, 240, 240)
        Note over Q,A: App Creation Phase
        Q->>+A: GET /status
        Note right of A: Must return 200 OK<br/>within 2 seconds
        A-->>-Q: 200 OK
    end

    rect rgb(240, 240, 240)
        Note over Q,A: Installation Phase
        Q->>+A: POST /installed
        Note right of A: Sends appSecret<br/>in request body
        A-->>-Q: Response (any HTTP code)
    end

    rect rgb(240, 240, 240)
        Note over Q,A: Activation Phase
        Q->>+A: GET /enabled?date=...&hmac=...
        A-->>-Q: Response (any HTTP code)
    end

    rect rgb(240, 240, 240)
        Note over Q,A: Optional: Deactivation
        Q->>+A: GET /disabled?date=...&hmac=...
        A-->>-Q: Response (any HTTP code)
    end

    rect rgb(240, 240, 240)
        Note over Q,A: Optional: Uninstallation
        Q->>+A: GET /uninstalled?date=...&hmac=...
        A-->>-Q: Response (any HTTP code)
    end

# Status Endpoint

Before app creation, Quable PIM checks the application status.

GET /status HTTP/1.1
Host: {{appUrl}}
Client-Id: Quable
Referer: {{instanceCode}}

⚠️ Important: Must return 200 HTTP Code within 2 seconds or app creation fails.

# Install Endpoint

Triggered once the QuableApp is created.

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

Request body:

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

Note: The appSecret is provided in the installation call body.

# Enable Endpoint

Called when the QuableApp is enabled.

GET /enabled?date=YYYMMDDTHHMMSS.XXX&hmac=... HTTP/1.1
Host: {{appUrl}}
Client-Id: Quable
Referer: {{instanceCode}}

# Disable Endpoint

Called when the QuableApp is disabled.

GET /disabled?date=YYYMMDDTHHMMSS.XXX&hmac=... HTTP/1.1
Host: {{appUrl}}
Client-Id: Quable
Referer: {{instanceCode}}

# Uninstall Endpoint

Called when the QuableApp is uninstalled.

GET /uninstalled?date=YYYMMDDTHHMMSS.XXX&hmac=... HTTP/1.1
Host: {{appUrl}}
Client-Id: Quable
Referer: {{instanceCode}}

# Installation Methods

# Interface Installation

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

# API Installation

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

# Slot Management

# Slot Subscription

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

# Slot Integration Example

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