# ConceptService

Top level api object from which all other api modules are available. ConceptService class

A Service class filled with utility functions for Concept items and enhanced data loading. ConceptService is accessed through the writer

Available operations to register callback handlers

## getPropertyMap()⇒ `object`

Get loaded property map

**Returns**: `object` - PropertyMap

## on(conceptType, operation, handler)

Function to register handlers for specific ConceptType operations

### Parameters

| Param       | Type       | Description                                                             |
| ----------- | ---------- | ----------------------------------------------------------------------- |
| conceptType | `string`   | **Required -** ex. 'x-im/category'                                      |
| operation   | `number`   | **Required -** ex. ConceptService.operations.ADD                        |
| handler     | `function` | **Required -** function that will be called when operation is triggered |

### Example

```js
ConceptService.on(
    'x-im/category',
    ConceptService.operations.ADD,
    this.handleNewCategory
)
```

## off(conceptType, operation, handler)

Function to remove registered handler

### Parameters

| Param       | Type       | Description                                                               |
| ----------- | ---------- | ------------------------------------------------------------------------- |
| conceptType | `string`   | **Required -** ex. 'x-im/category'                                        |
| operation   | `number`   | **Required -** ex. ConceptService.operations.ADD                          |
| handler     | `function` | **Required -** function that was registered as callback for the operation |

### Example

```js
ConceptService.off(
    'x-im/category',
     ConceptService.operations.ADD,
     this.handleNewCategory
)
```

## has(conceptType, operation)⇒ `boolean`

Function to check if a specific conceptType has a registered handler for a specific operation

**Returns**: `boolean` - if a handler has been registered

### Parameters

| Param       | Type     | Description                                               |
| ----------- | -------- | --------------------------------------------------------- |
| conceptType | `string` | **Required -** ex. 'x-im/category'                        |
| operation   | `number` | **Required -** ex. 'ADD' or ConceptService.operations.ADD |

### Example

```js
if (ConceptService.has('x-im/category', ConceptService.operations.ADD)) {
    // Do stuff
}
```

## trigger(operation, conceptItem)

Function to trigger registered handler for conceptType operations

### Parameters

| Param       | Type     | Description                                               |
| ----------- | -------- | --------------------------------------------------------- |
| operation   | `number` | **Required -** ex. 'ADD' or ConceptService.operations.ADD |
| conceptItem | `object` | **Required -** POJSO representation of a x-im concept     |

### Example

```js
ConceptService.trigger(
    ConceptService.operations.ADD,
    conceptItem = {
        uuid: xxx,
        create: true,
        ....
    }
)
```

## getArticleConceptByUUID(uuid)

Get article concept by uuid

### Parameters

| Param | Type    |
| ----- | ------- |
| uuid  | `sting` |

## getArticleConceptsByType(conceptType, multipleTypes, subtypes)⇒ `array`

Get concepts of a specific type, currently in the article

**Returns**: `array` - ConceptItems

### Parameters

| Param         | Type     | Description                                  |
| ------------- | -------- | -------------------------------------------- |
| conceptType   | `string` | **Required -** 'x-im/xxx'                    |
| multipleTypes | `array`  | **Required -** ex. \['x-im/xxx', 'x-im/yyy'] |
| subtypes      | `array`  | **Required -** ex. \['position', 'polygon']  |

## addArticleConcept(conceptItem, triggerDocumentChanged)

Add concept link to article

### Parameters

| Param                  | Type      | Default | Description                                                                            |
| ---------------------- | --------- | ------- | -------------------------------------------------------------------------------------- |
| conceptItem            | `object`  |         | **Required -** POJSO representation of a x-im concept                                  |
| triggerDocumentChanged | `boolean` | `true`  | **Required -** set to false to suppress document changed event, default is set to true |

## addArticleConcepts(conceptItems, triggerDocumentChanged)

Add an array of concept links to article

### Parameters

| Param                  | Type             | Default | Description                                                                            |
| ---------------------- | ---------------- | ------- | -------------------------------------------------------------------------------------- |
| conceptItems           | `Array.<object>` |         | **Required -** Array of POJSOs representation of a x-im concept                        |
| triggerDocumentChanged | `boolean`        | `true`  | **Required -** set to false to suppress document changed event, default is set to true |

## updateArticleChannelRel(conceptItem)

Update concept rel

### Parameters

| Param       | Type     | Description                                           |
| ----------- | -------- | ----------------------------------------------------- |
| conceptItem | `object` | **Required -** POJSO representation of a x-im concept |

## updateArticleConcept(conceptItem, triggerDocumentChanged)

Update existing concept link in article

### Parameters

| Param                  | Type      | Default | Description                                                                            |
| ---------------------- | --------- | ------- | -------------------------------------------------------------------------------------- |
| conceptItem            | `object`  |         | **Required -** POJSO representation of a x-im concept                                  |
| triggerDocumentChanged | `boolean` | `true`  | **Required -** set to false to suppress document changed event, default is set to true |

## ~~removeArticleConceptItem()~~

***Deprecated***

## removeArticleConcept(conceptItem)

Remove concept link from article

### Parameters

| Param       | Type     | Description                                           |
| ----------- | -------- | ----------------------------------------------------- |
| conceptItem | `object` | **Required -** POJSO representation of a x-im concept |

## removeArticleConcepts(conceptItems)

Remove an array of concept links from article

### Parameters

| Param        | Type             | Description                                                       |
| ------------ | ---------------- | ----------------------------------------------------------------- |
| conceptItems | `Array.<object>` | **Required -** Array of POJSOs representations of a x-im concepts |

## removeAllArticleLinksOfType(conceptType)

Remove all links of a specific type from the article

### Parameters

| Param       | Type     | Description                                             |
| ----------- | -------- | ------------------------------------------------------- |
| conceptType | `string` | **Required -** the concept type to remove from document |

## extractBroaderText(conceptItem, \[truncated])⇒ `string`

Recursive function to extract n number of parent names

**Returns**: `string` - Broader names combine

### Parameters

| Param       | Type      | Default | Description                                           |
| ----------- | --------- | ------- | ----------------------------------------------------- |
| conceptItem | `object`  |         | **Required -** POJSO representation of a x-im concept |
| truncated   | `boolean` | `false` |                                                       |

## getConceptItemXml(conceptItem)⇒ `string`

Get the actual concept XML from storage

**Returns**: `string` - XML response

### Parameters

| Param       | Type     | Description                                           |
| ----------- | -------- | ----------------------------------------------------- |
| conceptItem | `object` | **Required -** POJSO representation of a x-im concept |

## getConceptItemConfigJson(conceptItem)

Get the concept type config, cached or remote

### Parameters

| Param       | Type     | Description                                      |
| ----------- | -------- | ------------------------------------------------ |
| conceptItem | `object` | **Required -** POJSO representation of a concept |

## createConceptItemXml(xml)

Create a new concept item in storage

### Parameters

| Param | Type     |
| ----- | -------- |
| xml   | `string` |

## updateConceptItemXml(uuid, xml)

Update the actual concept item in storage

### Parameters

| Param | Type     |
| ----- | -------- |
| uuid  | `string` |
| xml   | `string` |

## fetchConceptItemProperties(conceptItem, string)⇒ `object`

fetch remaining props (not stored on the article) from oc

**Returns**: `object` - conceptItem

### Parameters

| Param       | Type          | Description                                           |
| ----------- | ------------- | ----------------------------------------------------- |
| conceptItem | `object`      | **Required -** POJSO representation of a x-im concept |
| string      | `object.uuid` | **Required -** must be a valid OC uuid                |

### Example

```js
import {ConceptService} from 'writer'

ConceptService.fetchConceptItemProperties({
     'uuid': '12345678-1234-4567-7891-789456123456'
})
```

## searchForConceptSuggestions(args, conceptTypes, term, subtypes, associatedWith, allowedStatuses, customQuery)⇒ `array`

Search for concepts

**Returns**: `array` - response An array with result objects

### Parameters

| Param           | Type                | Description                                                                                |
| --------------- | ------------------- | ------------------------------------------------------------------------------------------ |
| args            | `object`            | **Required -** Objects with search-related properties optional Arg-props                   |
| conceptTypes    | `string` \| `array` | **Required -** string or array, like 'x-im/story' or \['x-im/tag', 'x-im/category']        |
| term            | `string`            | **Required -** the term to look for in Concept name and description                        |
| subtypes        | `object`            | **Required -** \['position', 'polygon']                                                    |
| associatedWith  | `string`            | **Required -** x-im concept-type to which current type is associated, like 'x-im/channel'  |
| allowedStatuses | `array` \| `string` | **Required -** Optional array with allowed statuses                                        |
| customQuery     | `string`            | **Required -** Optional string with OC query to be included in search (like: Active:false) |

### Example

```js
const result = await ConceptService.searchForConceptSuggestions(
     conceptTypes: 'x-im/section',
     term: '*',
     subtypes: null,
     associatedWith: 'x-im/channel',
     allowedConceptStatuses = ["draft", "usable"]
)
```

## search(query)⇒ `array`

A search Concept function Will use submitted query to search for items with contenttype concept

**Returns**: `array` - searchResult

### Parameters

| Param | Type     | Description                                                                                 |
| ----- | -------- | ------------------------------------------------------------------------------------------- |
| query | `string` | **Required -** a open content query like "ConceptAuthorEmail:<robert.reporter@example.com>" |

## getRemoteConceptsByType(conceptType)⇒ `array`

Get concepts from remote storage by concept-type

**Returns**: `array` - array of concepts with matching type

### Parameters

| Param       | Type     | Description                     |
| ----------- | -------- | ------------------------------- |
| conceptType | `string` | **Required -** eg x-im/category |

## getGroupConcepts(groupType, includeConceptsWithoutGroup)

Get all concept-groups by group-type (subType), optionally include all concepts of subtype, that does not have an associated group

### Parameters

| Param                       | Type      | Default | Description                                                                                               |
| --------------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------- |
| groupType                   | `string`  |         | **Required -** what type should the group be set to handle (ConceptGroupSubTypeFull)                      |
| includeConceptsWithoutGroup | `boolean` | `false` | **Required -** include all concepts of subtype, that does not have an associated group, defaults to false |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.navigaglobal.com/writer/8.1.1/api-reference/writerapi/conceptservice.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.