> For the complete documentation index, see [llms.txt](https://docs.navigaglobal.com/writer/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.navigaglobal.com/writer/8.1.1/api-reference/writerapi/conceptservice.md).

# 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 |