### Making Your First API Call

Source: https://docs.zoominsoftware.com/bundle/zoomin-api/page/getting_started_with_the_zoomin_api

This section guides you through making a simple GET request to the `/search` endpoint to verify your API setup and authentication.

```APIDOC
## GET /api/user

### Description
Retrieves details about your user account using JWT authentication.

### Method
GET

### Endpoint
`{baseURL}/api/user`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **user_details** (object) - Contains information about the user account.

#### Response Example
```json
{
  "user_details": {
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "username": "example_user",
    "email": "user@example.com"
  }
}
```
```

--------------------------------

### Example Curated Queries Configuration in JSON

Source: https://docs.zoominsoftware.com/bundle/ZAC/page/how_to_manage_curated_queries

An example of a curated-queries.json file. It demonstrates how to define curated queries for multiple languages, mapping search terms like 'install' and 'Cluster-Aktivität' to specific internal and external resource URLs.

```json
{
  "enus": {
    "install": [
      "/bundle/IntegratedSwagger/page/topics/t_install.html",
      "/bundle/installation/resource/topics/product-installation.pdf",
      "https://stormsoftware.io/api-installation-doc.html"
    ]
  },
  "dede": {
    "Cluster-Aktivität": [
      "/bundle/IntegratedSwagger/page/topics/t_activate.html"
    ]   
  }
}
```

--------------------------------

### Example: Display Specific Pendo Guide by ID

Source: https://docs.zoominsoftware.com/bundle/IPH/page/integration_of_zoomin_in-product_help_and_pendo

An example demonstrating how to configure the Zoomin IPH widget's `onCloseWidgetCallback` to show a specific Pendo guide using its unique ID. This is useful for directing users to relevant content.

```javascript
widgetSettings: {
    onCloseWidgetCallback: function () {
      if (typeof pendo !== 'undefined') {
        pendo.showGuideById("GdhLPUGP1dRwI4GS9H4S_oTV1pU")
      }
    },
  }
```

--------------------------------

### Map language codes to installation resources in JSON

Source: https://docs.zoominsoftware.com/csh_context=3678830593

Provides a concrete JSON mapping of language codes to installation topic URLs and documents. Used for English (enus) and German (dede) to locate installation guides and related PDFs. No runtime dependencies; purely data configuration.

```JSON
{\n  "enus": {\n    "install": [\n      "/bundle/IntegratedSwagger/page/topics/t_install.html",\n      "/bundle/installation/resource/topics/product-installation.pdf",\n      "https://stormsoftware.io/api-installation-doc.html"\n    ]\n  },\n  "dede": {\n    "Cluster-Aktivität": [\n      "/bundle/IntegratedSwagger/page/topics/t_activate.html"\n    ]   \n  }\n}
```

--------------------------------

### JSON Synonyms Configuration Example

Source: https://docs.zoominsoftware.com/csh_context=3189604455

An example JSON configuration for search synonyms, demonstrating mappings for English ('enus') and an empty configuration for Spanish ('eses'). This snippet illustrates how to set up interchangeable terms like 'login' and 'signin', and how a search term like 'platform' can direct users to 'program'.

```json
[
  {
    "language": "enus",
    "synonyms": [
      "platform => program", 
      "login, signin => login, signin", 
      "rpm => revolutions per minute"
    ]
  },
  {
    "language": "eses",
    "synonyms": [
      
    ]
  }
]
```

--------------------------------

### Initialize Widget to Open on Start

Source: https://docs.zoominsoftware.com/bundle/IPH/page/how_to_control_zoomin_in-product_help_widget_default_visibility

Initializes a widget using a provided ID and host. This setup configures the widget to open automatically when the application starts, but it will remain closed initially.

```javascript
iph('init', {
      id: 1,
      host: "<domain-api>",
      widgetSettings: {
        openOnStart: true,
        visibleOnStart: false,
     }
   });
```

--------------------------------

### Deploying Zoomin In-Product Help Widget

Source: https://docs.zoominsoftware.com/bundle/IPH/page/how_to_specify_in-product_help_localization_strings_in_widget_settings

Guides on deploying the Zoomin In-Product Help web widget, including emulation, review, version selection, and self-hosting options.

```APIDOC
## Deploying Your Zoomin In-Product Help Web Widget

### Description
This section provides comprehensive instructions for deploying and managing the Zoomin In-Product Help web widget, ensuring it functions correctly in your application.

### Deployment Steps
* How to Emulate Your Zoomin In-Product Help Widget Before Deployment
* How to Review Your In-Product Help in the Zoomin Documentation Portal Playground Page
* How to Deploy Your Zoomin In-Product Help Web Widget
* How to Choose a widget.js Version in In-Product Help
* How to Self-Host the Zoomin In-Product Help JS Code
* About Zoomin In-Product Help Widget Settings
    * Examples of Available Widget Settings in Zoomin In-Product Help
* Zoomin In-Product Help JavaScript API Functions
```

--------------------------------

### Self-Hosting Zoomin In-Product Help JS Code

Source: https://docs.zoominsoftware.com/bundle/IPH/page/configuring_zoomin_in-product_help

Instructions on how to self-host the Zoomin In-Product Help JavaScript code. This allows for greater control over the widget's deployment and loading process. It typically involves downloading the `widget.js` file and including it in your application's HTML. No specific input/output, but requires access to the `widget.js` file.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Application</title>
    <!-- Include self-hosted widget.js -->
    <script src="/path/to/your/widget.js" async></script>
</head>
<body>
    <h1>Welcome to My Application</h1>
    <!-- Your application content -->

    <script>
        // Optional: Initialize widget configuration if needed
        // window.ZoominHelpConfig = {
        //     serverUrl: 'https://your.zoomin.domain.com',
        //     // other configuration options
        // };
    </script>
</body>
</html>
```

--------------------------------

### Confluence Configuration Example

Source: https://docs.zoominsoftware.com/bundle/ZCI/page/upload_server_custom_properties_configuration_options

Example configuration for uploading content from Confluence to the Zoomin Platform.  This provides various properties to filter and include specific content based on space, page, topics, and usernames.

```properties
args.input.path=mynewbook.ditamap
manual.name=mynewbook
booktitle=my new book title
shortdesc=These specifications describe the physical characteristics, \\n   performance, and operating conditions for the acme widget.\nspreadsheet.xml=subjectscheme.xml
document.locale=enus
```

--------------------------------

### Example Curated Queries Configuration

Source: https://docs.zoominsoftware.com/csh_context=3678830593

An example of a `curated-queries.json` file demonstrating how to configure curated search results for different languages and queries. It includes links to internal topics, resources, and external URLs.

```json
  {
    "enus": {
      "install": [
        "/bundle/IntegratedSwagger/page/topics/t_install.html",
        "/bundle/installation/resource/topics/product-installation.pdf",
        "https://stormsoftware.io/api-installation-doc.html"
      ]
    },
    "dede": {
      "Cluster-Aktivität": [
        "/bundle/IntegratedSwagger/page/topics/t_activate.html"
      ]   
    }
  } 
```

--------------------------------

### Define Getting Started Workflow Node in XML

Source: https://docs.zoominsoftware.com/bundle/ZDPT/page/how_to_create_dynamic_workflows_metro_maps_

This XML code creates a category node for a 'Getting Started with StormCluster' workflow, incorporating facets and an icon. Attributes such as display-tile-facets, displayName, slug, outputclass, shortDesc, and icon are used to define the node's properties. It assumes a compatible XML parser or CMS system, taking attribute strings as inputs and producing a node structure as output. Potential limitations involve specific framework requirements for facet and icon handling.

```xml
    <node type="category"
        slug="wf"
        outputclass="workflow"
        display-tile-facets="task-configuration"
        displayName="Getting Started with StormCluster"
        shortDesc="Getting Started with StormClster"
        icon="rocket.svg">
    </node>
```

--------------------------------

### Zoomin In-Product Help Widget Settings Examples

Source: https://docs.zoominsoftware.com/bundle/IPH/page/configuring_zoomin_in-product_help

Provides examples of various settings that can be configured for the Zoomin In-Product Help widget. These settings control the widget's appearance, behavior, and integration points. Configuration is typically done via a JavaScript object or through the Zoomin Admin Console. No specific code is provided, but implies a JSON-like structure for settings.

```javascript
// Example of widget settings configuration object
window.ZoominHelpConfig = {
  "serverUrl": "https://your.zoomin.domain.com",
  "widgetId": "unique-widget-identifier",
  "displayMode": "launcher", // or "embedded", "popup"
  "launcherColor": "#007bff",
  "launcherIcon": "question-circle",
  "title": "Help Center",
  "topics": {
    "defaultTopic": "welcome",
    "popularTopics": ["faq", "troubleshooting"]
  },
  "search": {
    "enabled": true,
    "placeholder": "Search help..."
  },
  "localization": {
    "locale": "en-US",
    "strings": {
      "closeButtonText": "Close",
      "searchPlaceholder": "Search documentation"
    }
  },
  "analytics": {
    "enabled": true,
    "trackingId": "UA-12345678-1"
  }
};
```

--------------------------------

### Full Example: Link to Installing Topic with Constraints

Source: https://docs.zoominsoftware.com/bundle/ZAC/page/how_to_link_to_a_topic_using_the_topic_file_name

This comprehensive snippet links to 'installing.dita' across multiple product models and versions by specifying pubname and facets. Ideal for referring to variant-specific installation instructions. Ensures resolution to the exact publication and classification; tested in Zoomin DITA environments.

```xml
<xref href="installing.dita" scope="peer">
     <data name="facets" value="pubname=userguide model=P256 version=3.0"/>
</xref>
```

--------------------------------

### Implement Zoomin In-Product Help Widget

Source: https://docs.zoominsoftware.com/csh_context=3089235976

Demonstrates the basic implementation of a Zoomin In-Product Help widget on a webpage. Requires including the Zoomin script and initializing the widget with basic configuration. The widget will appear as a floating element that users can interact with to access help content.

```html
<!DOCTYPE html>
<html>
<head>
    <title>Zoomin In-Product Help Implementation</title>
</head>
<body>
    <!-- Your application content -->
    <div id="app">
        <h1>My Application</h1>
        <p>Content goes here...</p>
    </div>

    <!-- Zoomin In-Product Help Script -->
    <script src="https://cdn.zoomin.software/widget/latest/zoomin-widget.min.js"></script>
    <script>
        // Initialize Zoomin widget
        zoomin.init({
            apiKey: "your-api-key",
            projectId: "your-project-id",
            // Additional configuration options
            defaultVisibility: true,
            location: {
                type: "floating",
                position: "bottom-right"
            }
        });
    </script>
</body>
</html>
```

--------------------------------

### Initialize SDK

Source: https://docs.zoominsoftware.com/bundle/IPH/page/zoomin_in-product_help_javascript_api_functions

Initializes the Zoomin Software SDK with a given ID and host.

```APIDOC
## Initialize SDK

### Description
Initializes the SDK for interacting with Zoomin Software features.

### Method
POST

### Endpoint
/init

### Parameters
#### Request Body
- **id** (integer) - Required - The initialization ID.
- **host** (string) - Required - The API host domain.

### Request Example
```json
{
  "id": 1,
  "host": "<domain-api>"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the initialization status.
```

--------------------------------

### Example Usage: Fetching a Zoomin Topic

Source: https://docs.zoominsoftware.com/bundle/zoomin-api/page/utilize_zoomin_topics_in_your_application_or_for_your_llm

Demonstrates how to use the JWT generation and topic retrieval functions. This script requires the 'PyJWT' and 'requests' libraries to be installed. Users need to fill in their specific publication name and topic path.

```python
# Assuming get_jwt_token and get_topic functions are defined above

if __name__ == '__main__':
    # fill in based on your use case
    publication_name = ''
    topic_path = ''

    # generate a JWT token
    token = get_jwt_token()

    # get topic information
    topic = get_topic(publication_name, topic_path, token)

    print(topic)
```

--------------------------------

### Implement Zoomin In-Product Help Widget

Source: https://docs.zoominsoftware.com/bundle/IPH/page/how_to_allow_users_to_filter_content_in_iph

This guide provides a checklist for implementing a Zoomin In-Product Help widget. It covers pre-requisite configurations and the steps to create or edit a web widget.

--------------------------------

### Example Meta Element for Version Tag in Zoomin

Source: https://docs.zoominsoftware.com/bundle/ZAC/page/how_zoomin_uses_meta_tags_to_expose_your_topics_to_external_crawlers

This example demonstrates the structure of a meta element generated by Zoomin Documentation Portal for a 'version' classification tag. It showcases how multiple version values (e.g., 1.0, 1.2, 1.7) are represented within the 'content' attribute, separated by semicolons, allowing external crawlers to identify and process version information associated with the topic.

```html
<meta name="zoomin:version" content="version-1_0, 1.0"; "version-1_2, 1.2"; "version-1_7, 1.7">
```

--------------------------------

### Create Internal Link List Tile in XML

Source: https://docs.zoominsoftware.com/bundle/ZDPT/page/link_list_tile_examples

This example demonstrates creating a link list tile that displays links to topics within a Zoomin Documentation Portal using XML in categories.xml. Requires a valid portal setup with specified bundles and URLs. Inputs include node and link elements; outputs are clickable links in the tile, limited to internal navigation within the same tab.

```xml
<node type="category"
  displayName="StormCluster Architecture"
  display-tile-facets="role-sysadmin"
  slug="storm-cluster-architecture"
  shortDesc="Introduction to the solution architecture of the StormCluster product line"
  icon="cloud.svg">
  <link type="internal"
     displayName="StormCluster Solution architecture overview"
     bundle="IntegratedSwagger"
     url="topics/c_architecture_overview.html"/>
  <link type="internal"
     displayName="Hardware and software requirements"
     bundle="IntegratedSwagger"
     url="topics/r_supported_platforms.html"/>
  <link type="internal"
     displayName="Component interaction"
     bundle="IntegratedSwagger"
     url="topics/c_components.html"/>
</node>
```

--------------------------------

### NewUser API

Source: https://docs.zoominsoftware.com/search_labelkey=cont-internal&page=110

API for creating a new user.

```APIDOC
## NewUser API

### Description
API for creating a new user.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Request Body
- **username** (string) - Required - The username for the new user.
- **email** (string) - Required - The email address of the new user.
- **role** (string) - Optional - The role assigned to the new user (e.g., 'admin', 'editor').

### Request Example
```json
{
  "username": "johndoe",
  "email": "john.doe@example.com",
  "role": "editor"
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the newly created user.
- **username** (string) - The username of the new user.
- **email** (string) - The email address of the new user.

#### Response Example
```json
{
  "id": "user_abcde",
  "username": "johndoe",
  "email": "john.doe@example.com"
}
```
```

--------------------------------

### XML: Subject Scheme for Content Type

Source: https://docs.zoominsoftware.com/csh_context=3162636307

This XML snippet defines a 'Content Type' classification within a subject scheme, providing examples of 'Guides' and 'Release Notes' as subject definitions with associated keys and navigation titles.

```xml
<subjectHead navtitle="Content Type"id="contype">
    <subjectdef keys="cont-guides" navtitle="Guides"/>
    <subjectdef keys="cont-rn" navtitle="Release Notes"/>
```

--------------------------------

### GET /api/announcements

Source: https://docs.zoominsoftware.com/bundle/zoomin-api-definition/page/index_operationid=model-categorysearchlink

Retrieves a list of announcements with optional filtering and sorting parameters. Supports filtering by announcement state (active, inactive, future, expired), display type (top banner, popup), and language. Results can be sorted by multiple criteria including priority, start date, name, and type.

```APIDOC
## GET /api/announcements

### Description
Retrieves announcements with filtering and sorting capabilities. Supports filtering by state, type, and language with various sorting options.

### Method
GET

### Endpoint
/api/announcements

### Parameters
#### Path Parameters
None

#### Query Parameters
- **state** (string) - Optional - Get announcements in specified state. Available values: future, expired, active, inactive
- **type** (string) - Optional - Get announcements by display position. Available values: topbanner, popup
- **lang** (string) - Optional - Get announcements for specified language
- **sort** (string) - Optional - Sort announcements in specified order. Available values: active-asc, active-desc, name-asc, name-desc, type-asc, type-desc, startdate-asc, startdate-desc, priority-asc, priority-desc, language-asc, language-desc

#### Request Body
None

### Request Example
```
GET /api/announcements?state=active&type=topbanner&sort=priority-asc
```

### Response
#### Success Response (200)
- **status** (string) - Announcement status
- **name** (string) - Announcement name
- **type** (string) - Announcement display type
- **startTime** (string) - Start timestamp in ISO format
- **endTime** (string) - End timestamp in ISO format
- **priority** (number) - Priority number
- **language** (string) - Language code
- **id** (number) - Announcement ID
- **annHtml** (string) - Announcement HTML content
- **clickUrl** (string) - Click-through URL
- **css** (string) - CSS styling
- **caption** (string) - Announcement caption

#### Response Example
```json
[
  {
    "status": "AnnActive",
    "name": "New Feature Announcement",
    "type": "AnnTopBanner",
    "startTime": "2024-07-31T12:30:00Z",
    "endTime": "2024-08-31T12:30:00Z",
    "priority": 1,
    "language": "enus",
    "id": 9999,
    "annHtml": "Hear ye, hear ye!",
    "clickUrl": "https://example.com/announcement-target.html",
    "css": "color: red;",
    "caption": "New Feature"
  }
]
```

#### Error Response (400)
- **error** (string) - Error message

#### Error Response Example
```json
"Bad Request"
```
```

--------------------------------

### Request Connector Setup via Email Template

Source: https://docs.zoominsoftware.com/bundle/ZCI/page/about_the_salesforce_discussion_connector

This template provides a formatted email structure for contacting Zoomin support to initiate a Salesforce Discussions connector setup. It incorporates placeholders for company details, user credentials, permissions, domain, and API token, outputting a ready-to-send message. No programming dependencies are needed, but manual value substitution and email delivery are required; ensure all placeholders are filled accurately to avoid setup delays.

```text
Dear Zoomin Suppport,
Please create a Salesforce Discussions Connector for <name of Company>.
My Zoomin Community Member User Name is: <user>. 
This user <can or cannot> be granted view all data permissions. 
My Domains is: <Domain>
My API token is: <token>

Thank you,
Your Name
```

--------------------------------

### JWT Authentication Code Examples

Source: https://docs.zoominsoftware.com/bundle/IPH/page/how_to_present_topic_snippets_in_zoomin_in-product_help_search_results

Examples of generating JSON Web Tokens (JWT) for authenticating users with Zoomin In-Product Help. These examples demonstrate how to create and use JWTs to control access and personalize user experiences.

```JavaScript
const jwt = require('jsonwebtoken');
const secret = 'your-secret-key';
const payload = {
  sub: 'user123',
  roles: ['admin']
};
const token = jwt.sign(payload, secret, { algorithm: 'HS256' });
console.log(token);
```

```Python
import jwt
payload = {"sub": "user123", "roles": ["admin"]}
secret = "your-secret-key"
token = jwt.encode(payload, secret, algorithm="HS256")
print(token)
```

--------------------------------

### Configure JSON Synonyms for Multiple Languages

Source: https://docs.zoominsoftware.com/csh_context=3189604455

This JSON structure defines search synonyms for different languages. It includes mappings for terms like 'install', 'platform', 'login', and 'rpm' in English ('enus') and demonstrates an example for Spanish ('eses'). It's used to improve search relevance by linking related terms.

```json
[
  {
    "language": "enus",
    "synonyms": [
      "install, download, configure, => install",
      "platform => program", 
      "login, signin => login, signin", 
      "rpm => revolutions per minute"
    ]
  },
  {
    "language": "eses",
    "synonyms": [
      "instalar, poner, instalarse => instalar, poner, instalarse"
    ]
  }
]
```