Entity

https://github.com/xm-online/xm-ms-entity
Admin
An entity microservice application generated with JHipster, designed for a microservice architecture...
Tokens:21,801
Snippets:86
Trust Score:8.1
License:Apache-2.0
Update:8 months ago
Show doc for...
Tokens:
Raw
### Groovy LEP Unit Test Structure Example

Source: https://github.com/xm-online/xm-ms-entity/blob/master/src/test/groovy/README.md

This snippet demonstrates the typical structure of a Groovy LEP unit test, including imports, test setup, script evaluation, and assertions. It utilizes `AbstractGroovyUnitTest` and Mockito for mocking dependencies.

```Groovy
package XM.entity.test.service.entity

import com.icthh.xm.commons.exceptions.BusinessException
import com.icthh.xm.lep.AbstractGroovyUnitTest
import com.icthh.xm.ms.entity.domain.Link
import com.icthh.xm.ms.entity.domain.XmEntity
import org.junit.Before
import org.junit.Test
import org.mockito.MockitoAnnotations

import static groovy.test.GroovyAssert.shouldFail
import static org.mockito.ArgumentMatchers.any
import static org.mockito.Mockito.mock
import static org.mockito.Mockito.verifyZeroInteractions
import static org.mockito.Mockito.verify
import static org.mockito.Mockito.when
import static org.mockito.Mockito.withSettings

class SaveAgreementUnitTest extends AbstractGroovyUnitTest {

    String scriptName = resolveScriptName('/service/entity/Save$$AGREEMENT$$around.groovy')

    Closure linkEntities

    @Override
    @Before
    void setUp() {
        super.setUp()
        linkEntities = mock(Closure.class, withSettings().useConstructor(this))
    }

    @Override
    Object setLepContext() {
        MockitoAnnotations.initMocks(this)
        [
                lep    : [
                        proceed           : { buildAgreement() },
                        getMethodArgValues: { '' }
                ],
                commons: [
                        linkUtils: {
                            [
                                    linkEntities: linkEntities
                            ]
                        }
                ]
        ]
    }

    @Test
    void execFunc_SAVE_success() {
        when(linkEntities.call(any(), any(), any(), any())).thenReturn([])

        XmEntity agreement = evaluateScript(scriptName)

        assert agreement
        assert agreement.id == 1L
        assert agreement.sources

        verify(linkEntities).call('PARTY.AGREEMENT',
                'AGREEMENT.PARTY',
                buildParty(),
                buildEmptyLinksEntity())

    }

    @Test
    void execFunc_SAVE_orderLinksNotFoundException() {
        lepContext.lep.proceed = { buildEmptyLinksEntity() }

        def e = shouldFail {
            evaluateScript(scriptName)
        }

        verifyZeroInteractions(linkEntities)

        assert e instanceof BusinessException
        assert e.code == 'error.agreement.no.links.found'
        assert e.message == 'The are no links with state = ORDER.AGREEMENT'
    }

    @Test
    void execFunc_SAVE_partyLinksNotFoundException() {
        lepContext.lep.proceed = { buildAgreementNoParties() }

        def e = shouldFail {
            evaluateScript(scriptName)
        }

        verifyZeroInteractions(linkEntities)

        assert e instanceof BusinessException
        assert e.code == 'error.order.no.links.found'
        assert e.message == 'The are no links with state = ORDER.PARTY'
    }

    private static XmEntity buildEmptyLinksEntity() {
        [id: 1L] as XmEntity
    }


    private static XmEntity buildParty() {
        [id: 100L] as XmEntity
    }

    private static Set<Link> buildOrderLinks() {
        [
                [
                        typeKey: 'ORDER.AGREEMENT',
                        source : buildEmptyLinksEntity()
                ] as Link,
                [
                        typeKey: 'ORDER.OTHER_LINK'
                ] as Link
        ] as Set
    }

    private static List<Link> buildPartyLinks() {
        [
                [
                        typeKey: 'ORDER.PARTY',
                        target : buildParty()
                ] as Link
        ]
    }

    private static XmEntity buildAgreement() {
        XmEntity agreement = buildEmptyLinksEntity()

        def links = buildOrderLinks()

        links.find { it -> it.typeKey == 'ORDER.AGREEMENT' }
                .source
                .targets =
                buildPartyLinks()
        agreement.sources = links
        agreement
    }

    private static XmEntity buildAgreementNoParties() {
        XmEntity agreement = buildEmptyLinksEntity()
        agreement.sources = buildOrderLinks()
        agreement
    }
}
```

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

### Setup Environment Variables for Tenant LEP Testing (Shell)

Source: https://github.com/xm-online/xm-ms-entity/blob/master/src/test/groovy/README.md

Sets up essential environment variables for manual LEP testing, including paths to the configuration repository, tenant name, and LEP directories. These variables are crucial for creating symlinks.

```shell
export XM_REPOSITORY_HOME=<path_to_ms_config>/xm-ms-config-repository
export tenant=<tenant>
export tenant_upper=`echo $tenant | tr a-z A-Z`

export LEP_TEST_HOME=./src/test/lep
export LEP_SCRIPT_HOME=./src/main/lep
```

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

### Execute Entity Functions (GET and POST)

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Triggers custom business logic (LEP scripts) on entities. Supports GET requests for data retrieval and POST requests for actions or mutations, with dynamic results based on the function's implementation.

```curl
# Execute a GET function (for retrieving data)
curl -X GET "http://localhost:8080/api/xm-entities/1/functions/CALCULATE-DISCOUNT?productId=123&quantity=10" \
  -H "Authorization: Bearer <token>"
```

```curl
# Execute a POST function (for actions/mutations)
curl -X POST "http://localhost:8080/api/xm-entities/1/functions/SEND-NOTIFICATION" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "channel": "email",
    "template": "ORDER_CONFIRMATION",
    "recipients": ["customer@example.com"]
  }'
```

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

### Function Context API - Get All Contexts

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Retrieves a list of all function contexts. Requires a valid authorization token.

```bash
curl -X GET "http://localhost:8080/api/function-contexts" \
  -H "Authorization: Bearer <token>"
```

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

### Run All Entity LEP Tests with Gradle (Shell)

Source: https://github.com/xm-online/xm-ms-entity/blob/master/src/test/groovy/README.md

Executes all LEP tests related to the entity microservice using Gradle. This command is useful for running a comprehensive test suite for the entity service.

```shell
./gradlew runCategorizedTests --tests *.entity.test.*
```

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

### Run Specific LEP Tests with Gradle (Shell)

Source: https://github.com/xm-online/xm-ms-entity/blob/master/src/test/groovy/README.md

Executes specific LEP unit tests within the entity microservice context using Gradle. This command allows for targeted testing of individual test cases.

```shell
./gradlew runCategorizedTests --tests <MyTestName>
```

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

### Run LEP Test Link Scanner (Java)

Source: https://github.com/xm-online/xm-ms-entity/blob/master/src/test/groovy/README.md

Executes the LEP test link scanner to create configuration repository links for tenants with a 'test' folder in the entity microservice. Requires Java 11 or higher.

```java
java src/test/java/com/icthh/xm/ms/entity/LepTestLinkScanner.java <path/to/xm-config-repository>
```

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

### Create Symlink to Tenant Unit Tests (Shell)

Source: https://github.com/xm-online/xm-ms-entity/blob/master/src/test/groovy/README.md

Creates a symbolic link from the local LEP test directory to the tenant's unit test directory within the configuration repository. This allows the service to access tenant-specific unit tests.

```shell
mkdir -p $LEP_TEST_HOME
ln -s $XM_REPOSITORY_HOME/config/tenants/$tenant_upper/entity/test/ $LEP_TEST_HOME/$tenant_upper/entity/test
```

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

### Links Management API - Get Links

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Retrieves a paginated list of all link entities. Supports 'page' and 'size' query parameters for pagination. Requires an authorization token.

```bash
curl -X GET "http://localhost:8080/api/links?page=0&size=50" \
  -H "Authorization: Bearer <token>"
```

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

### GET /api/v2/xm-entities/{id}/links/sources

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Retrieves source links with pagination support for a given entity.

```APIDOC
## GET /api/v2/xm-entities/{id}/links/sources

### Description
Retrieves source links with pagination support for a given entity.

### Method
GET

### Endpoint
/api/v2/xm-entities/{id}/links/sources

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the entity.

#### Query Parameters
- **typeKeys** (string) - Optional - Comma-separated list of entity type keys to filter by.
- **page** (integer) - Optional - The page number for pagination (default is 0).
- **size** (integer) - Optional - The number of items per page (default is 10).

#### Request Body
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/v2/xm-entities/1/links/sources?typeKeys=ORDER,INVOICE&page=0&size=10" \
  -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **links** (array) - A list of source links.
  - **id** (integer) - The ID of the linked entity.
  - **typeKey** (string) - The type key of the linked entity.
  - **name** (string) - The name of the linked entity.
- **page** (integer) - The current page number.
- **size** (integer) - The number of items per page.
- **totalElements** (integer) - The total number of elements.
- **totalPages** (integer) - The total number of pages.

#### Response Example
```json
{
  "links": [
    {
      "id": 2,
      "typeKey": "ORDER",
      "name": "Order #123"
    }
  ],
  "page": 0,
  "size": 10,
  "totalElements": 1,
  "totalPages": 1
}
```
```

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

### Manage Entity Tags (Create, Get, Delete)

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Enables a flexible labeling system for entities. Allows creating tags with type, name, and associated entity, retrieving all tags, and deleting tags by ID.

```curl
# Create a tag
curl -X POST "http://localhost:8080/api/tags" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "typeKey": "PRIORITY.HIGH",
    "name": "High Priority",
    "startDate": "2024-01-15T00:00:00Z",
    "xmEntity": {"id": 1}
  }'
```

```curl
# Get all tags
curl -X GET "http://localhost:8080/api/tags" \
  -H "Authorization: Bearer <token>"
```

```curl
# Delete a tag
curl -X DELETE "http://localhost:8080/api/tags/1" \
  -H "Authorization: Bearer <token>"
```

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

### Create Symlink to Tenant Entity LEPs (Shell)

Source: https://github.com/xm-online/xm-ms-entity/blob/master/src/test/groovy/README.md

Creates a symbolic link from the local LEP script directory to the tenant's entity LEP scripts within the configuration repository. This enables the service to load and execute tenant-specific LEP functions.

```shell
mkdir -p $LEP_SCRIPT_HOME
ln -s $XM_REPOSITORY_HOME/config/tenants/$tenant_upper/entity/lep $LEP_SCRIPT_HOME/$tenant_upper/entity/lep
```

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

### Manage Entity Attachments (Create, Get, Delete)

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Handles file attachments associated with entities. Supports creating attachments with metadata and content, retrieving attachments by ID, and deleting attachments.

```curl
# Create an attachment
curl -X POST "http://localhost:8080/api/attachments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "typeKey": "DOCUMENT.INVOICE",
    "name": "Invoice-2024-001.pdf",
    "contentChecksum": "sha256:abc123...",
    "content": {
      "value": "base64encodedcontent..."
    },
    "xmEntity": {"id": 1}
  }'
```

```curl
# Get attachment by ID
curl -X GET "http://localhost:8080/api/attachments/1" \
  -H "Authorization: Bearer <token>"
```

```curl
# Get download link for attachment
curl -X GET "http://localhost:8080/api/attachments/1/download-link" \
  -H "Authorization: Bearer <token>"
```

```curl
# Delete an attachment
curl -X DELETE "http://localhost:8080/api/attachments/1" \
  -H "Authorization: Bearer <token>"
```

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

### Function Context API - Get Context by ID

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Retrieves a specific function context by its ID. Requires a valid authorization token.

```bash
curl -X GET "http://localhost:8080/api/function-contexts/1" \
  -H "Authorization: Bearer <token>"
```

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

### Get Entity Source Links (v1 and v2)

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Retrieves entities that link to a specified entity. Supports basic retrieval and advanced retrieval with pagination and filtering by type keys using the v2 API.

```curl
curl -X GET "http://localhost:8080/api/xm-entities/1/links/sources" \
  -H "Authorization: Bearer <token>"
```

```curl
curl -X GET "http://localhost:8080/api/v2/xm-entities/1/links/sources?typeKeys=ORDER,INVOICE&page=0&size=10" \
  -H "Authorization: Bearer <token>"
```

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

### Manage Entity Locations (Create, Get)

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Manages geographic locations associated with entities. Supports creating locations with detailed address information, coordinates, and custom types, as well as retrieving all locations.

```curl
# Create a location
curl -X POST "http://localhost:8080/api/locations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "typeKey": "ADDRESS.SHIPPING",
    "name": "Headquarters",
    "countryKey": "US",
    "addressLine1": "123 Main Street",
    "addressLine2": "Suite 100",
    "city": "San Francisco",
    "region": "CA",
    "zip": "94102",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "xmEntity": {"id": 1}
  }'
```

```curl
# Get all locations
curl -X GET "http://localhost:8080/api/locations" \
  -H "Authorization: Bearer <token>"
```

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

### Manage Entity Comments (Create, Get, Update, Delete)

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Provides functionality for threaded discussions on entities. Supports creating new comments, retrieving comments with pagination, updating existing comments, and deleting comments.

```curl
# Create a comment
curl -X POST "http://localhost:8080/api/comments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "message": "This order needs expedited processing",
    "userKey": "user123",
    "xmEntity": {"id": 1}
  }'
```

```curl
# Get comments for an entity with pagination
curl -X GET "http://localhost:8080/api/xm-entities/1/comments?page=0&size=20" \
  -H "Authorization: Bearer <token>"
```

```curl
# Update a comment
curl -X PUT "http://localhost:8080/api/comments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "id": 1,
    "message": "Updated comment text",
    "xmEntity": {"id": 1}
  }'
```

```curl
# Delete a comment
curl -X DELETE "http://localhost:8080/api/comments/1" \
  -H "Authorization: Bearer <token>"
```

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

### GET /api/xm-entities/{id}/links/sources

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Retrieves source links (entities that link to this entity) for a given entity.

```APIDOC
## GET /api/xm-entities/{id}/links/sources

### Description
Retrieves source links (entities that link to this entity) for a given entity.

### Method
GET

### Endpoint
/api/xm-entities/{id}/links/sources

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the entity.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET "http://localhost:8080/api/xm-entities/1/links/sources" \
  -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **links** (array) - A list of source links.
  - **id** (integer) - The ID of the linked entity.
  - **typeKey** (string) - The type key of the linked entity.
  - **name** (string) - The name of the linked entity.

#### Response Example
```json
{
  "links": [
    {
      "id": 2,
      "typeKey": "ORDER",
      "name": "Order #123"
    }
  ]
}
```
```

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

### Entity Functions API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Executes custom business logic (LEP scripts) on entities. Functions can be triggered via GET or POST methods and return dynamic results.

```APIDOC
## Entity Functions API

### Description
Functions allow executing custom business logic (LEP scripts) on entities. Functions can be triggered via GET or POST methods and return dynamic results based on the implemented logic.

### GET /api/xm-entities/{id}/functions/{functionKey}

#### Description
Executes a GET function for retrieving data.

#### Method
GET

#### Endpoint
/api/xm-entities/{id}/functions/{functionKey}

#### Parameters
##### Path Parameters
- **id** (integer) - Required - The ID of the entity.
- **functionKey** (string) - Required - The key of the function to execute.

##### Query Parameters
- **[paramName]** (string) - Optional - Parameters required by the function.

#### Request Example
```bash
curl -X GET "http://localhost:8080/api/xm-entities/1/functions/CALCULATE-DISCOUNT?productId=123&quantity=10" \
  -H "Authorization: Bearer <token>"
```

### POST /api/xm-entities/{id}/functions/{functionKey}

#### Description
Executes a POST function for actions or mutations.

#### Method
POST

#### Endpoint
/api/xm-entities/{id}/functions/{functionKey}

#### Parameters
##### Path Parameters
- **id** (integer) - Required - The ID of the entity.
- **functionKey** (string) - Required - The key of the function to execute.

##### Query Parameters
None

##### Request Body
- **[field]** (any) - Optional - The request body required by the function.

#### Request Example
```bash
curl -X POST "http://localhost:8080/api/xm-entities/1/functions/SEND-NOTIFICATION" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{ 
    "channel": "email",
    "template": "ORDER_CONFIRMATION",
    "recipients": ["customer@example.com"]
  }'
```

### Response
#### Success Response (200)
- **[field]** (any) - The dynamic result of the function execution.

#### Response Example
```json
{
  "success": true,
  "notificationId": "notif-12345",
  "sentAt": "2024-01-15T10:30:00Z"
}
```
```

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

### Calendar and Events API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Provides API endpoints for managing calendars and events. Supports creating calendars, retrieving events with date filtering, creating new events, and fetching all events. Requires authentication.

```bash
# Create a calendar
curl -X POST "http://localhost:8080/api/calendars" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "typeKey": "CALENDAR.PROJECT",
    "name": "Project Milestones",
    "xmEntity": {"id": 1}
  }'
```

```bash
# Get calendar events with date filter
curl -X GET "http://localhost:8080/api/calendars/1/events?dateFrom=2024-01-01&dateTo=2024-12-31&page=0&size=50" \
  -H "Authorization: Bearer <token>"
```

```bash
# Create an event
curl -X POST "http://localhost:8080/api/events" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "typeKey": "EVENT.MEETING",
    "title": "Project Kickoff",
    "description": "Initial project planning meeting",
    "startDate": "2024-02-01T09:00:00Z",
    "endDate": "2024-02-01T10:00:00Z",
    "calendar": {"id": 1}
  }'
```

```bash
# Get all events
curl -X GET "http://localhost:8080/api/events" \
  -H "Authorization: Bearer <token>"
```

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

### Storage API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Handles file uploads to object storage, with support for optional image resizing for avatars.

```APIDOC
## Storage API Endpoints

### Upload a file to storage

#### Method
POST

#### Endpoint
/api/storage/objects

#### Description
Uploads a file to the configured object storage.

#### Form Data
- **file** (file) - Required - The file to upload.

#### Response
#### Success Response (200)
- **(URL of the uploaded file)**

#### Response Example
```
"https://s3.amazonaws.com/bucket/path/to/uploaded-file.jpg"
```

### Upload with avatar resizing

#### Method
POST

#### Endpoint
/api/storage/objects?size={size}

#### Description
Uploads a file to object storage and resizes it as an avatar.

#### Query Parameters
- **size** (integer) - Optional - The desired size for the avatar in pixels (e.g., 200).

#### Form Data
- **file** (file) - Required - The image file to upload and resize.

#### Response
#### Success Response (200)
- **(URL of the uploaded and resized avatar)**

#### Response Example
```
"https://s3.amazonaws.com/bucket/path/to/resized-avatar.png"
```
```

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

### Manage Entity States via REST API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Enables workflow transitions for entities using a state machine model. Allows updating an entity's state with optional context data passed during the transition. Requires authentication.

```bash
# Update entity state with context data
curl -X PUT "http://localhost:8080/api/xm-entities/1/states/APPROVED" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "approvedBy": "admin@example.com",
    "approvalDate": "2024-01-15T14:30:00Z",
    "notes": "All requirements met"
  }'

# Response:
# {
#   "id": 1,
#   "typeKey": "ORDER.PURCHASE",
#   "stateKey": "APPROVED",
#   "name": "Order #12345",
#   ...
# }
```

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

### Function Context API - Create Context

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Creates a new function context to store execution results and metadata. Requires a JSON payload with context details including key, typeKey, data, and associated xmEntity. An authorization token is mandatory.

```bash
curl -X POST "http://localhost:8080/api/function-contexts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "key": "CALC-2024-001",
    "typeKey": "FUNCTION.CALCULATION",
    "description": "Price calculation result",
    "data": {
      "input": {"productId": 123, "quantity": 10},
      "output": {"totalPrice": 999.99, "discount": 10}
    },
    "xmEntity": {"id": 1}
  }'
```

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

### Storage API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Enables file uploads to object storage, supporting optional image resizing for avatars. Files are uploaded using multipart/form-data. Requires authentication and returns the URL of the uploaded file.

```bash
# Upload a file to storage
curl -X POST "http://localhost:8080/api/storage/objects" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/image.jpg"
```

```bash
# Upload with avatar resizing
curl -X POST "http://localhost:8080/api/storage/objects?size=200" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/avatar.png"
```

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

### Profile API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Manages user profiles, allowing self-service access to the current user's profile and administrative access by user key. Supports retrieving and updating the current user's profile, and retrieving profiles by user key. Requires authentication.

```bash
# Get current user's profile
curl -X GET "http://localhost:8080/api/profile" \
  -H "Authorization: Bearer <token>"
```

```bash
# Update current user's profile
curl -X PUT "http://localhost:8080/api/profile" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "id": 1,
    "name": "Updated Name",
    "data": {
      "preferences": {
        "theme": "dark",
        "language": "en"
      }
    }
  }'
```

```bash
# Get profile by user key (admin)
curl -X GET "http://localhost:8080/api/profile/user123" \
  -H "Authorization: Bearer <token>"
```

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

### Manage Entity Links via REST API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Establishes relationships between entities with typed connections. Supports retrieving target links for an entity and creating new links, optionally with file attachments. Requires authentication.

```bash
# Get all target links for an entity
curl -X GET "http://localhost:8080/api/xm-entities/1/links/targets?typeKey=CUSTOMER.CONTACT" \
  -H "Authorization: Bearer <token>"

# Create a link with optional file attachment
curl -X POST "http://localhost:8080/api/xm-entities/1/links/targets" \
  -H "Authorization: Bearer <token>" \
  -F 'link={"typeKey":"DOCUMENT.CONTRACT","name":"Service Agreement","target":{"id":2}};type=application/json' \
  -F 'file=@/path/to/contract.pdf'
```

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

### Search API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Provides full-text search capabilities for entities, powered by Elasticsearch. Supports basic queries, v2 searches with include/exclude fields, searching by type key, template-based searches, and searching for entities to link. Requires authentication.

```bash
# Basic search
curl -X GET "http://localhost:8080/api/_search/xm-entities?query=John%20Doe&page=0&size=20" \
  -H "Authorization: Bearer <token>"
```

```bash
# Search v2 with source filtering
curl -X GET "http://localhost:8080/api/_search/v2/xm-entities?query=name:John*&includes=id,name,typeKey&excludes=data" \
  -H "Authorization: Bearer <token>"
```

```bash
# Search by type key
curl -X GET "http://localhost:8080/api/_search-with-typekey/xm-entities?typeKey=CUSTOMER&query=active:true" \
  -H "Authorization: Bearer <token>"
```

```bash
# Template-based search
curl -X GET "http://localhost:8080/api/_search-with-template/xm-entities?template=CUSTOMER_SEARCH&status=active&region=US" \
  -H "Authorization: Bearer <token>"
```

```bash
# Search for entities to link
curl -X GET "http://localhost:8080/api/xm-entities/CUSTOMER/1/links/ORDER/search?query=status:pending" \
  -H "Authorization: Bearer <token>"
```

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

### Tags API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Provides a flexible labeling system for entities, allowing categorization and filtering based on custom tag types.

```APIDOC
## Tags API

### Description
Tags provide a flexible labeling system for entities, allowing categorization and filtering based on custom tag types.

### POST /api/tags

#### Description
Creates a new tag for an entity.

#### Method
POST

#### Endpoint
/api/tags

#### Parameters
##### Path Parameters
None

##### Query Parameters
None

##### Request Body
- **typeKey** (string) - Required - The type key of the tag.
- **name** (string) - Required - The name of the tag.
- **startDate** (string) - Optional - The start date for the tag (ISO 8601 format).
- **xmEntity** (object) - Required - The entity associated with the tag.
  - **id** (integer) - Required - The ID of the entity.

#### Request Example
```bash
curl -X POST "http://localhost:8080/api/tags" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{ 
    "typeKey": "PRIORITY.HIGH",
    "name": "High Priority",
    "startDate": "2024-01-15T00:00:00Z",
    "xmEntity": {"id": 1}
  }'
```

### GET /api/tags

#### Description
Retrieves all tags.

#### Method
GET

#### Endpoint
/api/tags

#### Parameters
None

#### Request Example
```bash
curl -X GET "http://localhost:8080/api/tags" \
  -H "Authorization: Bearer <token>"
```

### DELETE /api/tags/{id}

#### Description
Deletes a tag by its ID.

#### Method
DELETE

#### Endpoint
/api/tags/{id}

#### Parameters
##### Path Parameters
- **id** (integer) - Required - The ID of the tag to delete.

##### Query Parameters
None

##### Request Body
None

#### Request Example
```bash
curl -X DELETE "http://localhost:8080/api/tags/1" \
  -H "Authorization: Bearer <token>"
```

### Response (for GET, POST, DELETE)
#### Success Response (200)
- **id** (integer) - The ID of the tag.
- **typeKey** (string) - The type key of the tag.
- **name** (string) - The name of the tag.
- **startDate** (string) - The start date of the tag.
- **xmEntityId** (integer) - The ID of the associated entity.
- **message** (string) - A success message (for POST, DELETE).

#### Response Example (GET)
```json
[
  {
    "id": 1,
    "typeKey": "PRIORITY.HIGH",
    "name": "High Priority",
    "startDate": "2024-01-15T00:00:00Z",
    "xmEntityId": 1
  }
]
```

#### Response Example (POST/DELETE)
```json
{
  "message": "Tag created successfully."
}
```
```

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

### Manage XmEntity Objects via REST API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Provides CRUD operations for XmEntity objects, allowing creation, retrieval, update, and deletion. Supports filtering, pagination, and embedding related collections like tags, locations, and attachments. Requires authentication via Bearer token.

```bash
# Create a new entity
curl -X POST "http://localhost:8080/api/xm-entities" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "key": "CUST-001",
    "typeKey": "CUSTOMER.INDIVIDUAL",
    "stateKey": "ACTIVE",
    "name": "John Doe",
    "description": "Premium customer account",
    "startDate": "2024-01-15T10:00:00Z",
    "data": {
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "preferences": {
        "language": "en",
        "notifications": true
      }
    }
  }'

# Response:
# {
#   "id": 1,
#   "key": "CUST-001",
#   "typeKey": "CUSTOMER.INDIVIDUAL",
#   "stateKey": "ACTIVE",
#   "name": "John Doe",
#   "startDate": "2024-01-15T10:00:00Z",
#   "updateDate": "2024-01-15T10:00:00Z",
#   "data": {...}
# }

# Get entity by ID or key
curl -X GET "http://localhost:8080/api/xm-entities/1" \
  -H "Authorization: Bearer <token>"

curl -X GET "http://localhost:8080/api/xm-entities/CUST-001" \
  -H "Authorization: Bearer <token>"

# Get entity with embedded collections
curl -X GET "http://localhost:8080/api/xm-entities/1?embed=tags,locations,attachments" \
  -H "Authorization: Bearer <token>"

# Get all entities with pagination and type filter
curl -X GET "http://localhost:8080/api/xm-entities?page=0&size=20&typeKey=CUSTOMER" \
  -H "Authorization: Bearer <token>"

# Get multiple entities by IDs
curl -X GET "http://localhost:8080/api/xm-entities-by-ids?ids=1,2,3&embed=tags" \
  -H "Authorization: Bearer <token>"

# Update an entity
curl -X PUT "http://localhost:8080/api/xm-entities" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "id": 1,
    "key": "CUST-001",
    "typeKey": "CUSTOMER.INDIVIDUAL",
    "stateKey": "ACTIVE",
    "name": "John Doe Updated",
    "data": {
      "email": "john.updated@example.com"
    }
  }'

# Delete an entity
curl -X DELETE "http://localhost:8080/api/xm-entities/1" \
  -H "Authorization: Bearer <token>"
```

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

### Search API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Provides full-text search capabilities using Elasticsearch, supporting various query types and filtering options.

```APIDOC
## Search API Endpoints

### Basic search

#### Method
GET

#### Endpoint
/api/_search/xm-entities

#### Description
Performs a basic full-text search on xm-entities.

#### Query Parameters
- **query** (string) - Required - The search query string.
- **page** (integer) - Optional - The page number for pagination (defaults to 0).
- **size** (integer) - Optional - The number of items per page (defaults to 20).

#### Response
#### Success Response (200)
- **(Search results)**

#### Response Example
```json
(Array of search result objects)
```

### Search v2 with source filtering

#### Method
GET

#### Endpoint
/api/_search/v2/xm-entities

#### Description
Performs a search with advanced options including source field inclusion and exclusion.

#### Query Parameters
- **query** (string) - Required - The search query string (e.g., "name:John*").
- **includes** (string) - Optional - Comma-separated list of fields to include in the results.
- **excludes** (string) - Optional - Comma-separated list of fields to exclude from the results.

#### Response
#### Success Response (200)
- **(Search results with specified fields)**

#### Response Example
```json
(Array of search result objects with filtered fields)
```

### Search by type key

#### Method
GET

#### Endpoint
/api/_search-with-typekey/xm-entities

#### Description
Searches for entities of a specific type key.

#### Query Parameters
- **typeKey** (string) - Required - The type key of the entities to search for (e.g., "CUSTOMER").
- **query** (string) - Required - The search query string (e.g., "active:true").

#### Response
#### Success Response (200)
- **(Search results for the specified type key)**

#### Response Example
```json
(Array of search result objects matching the type key and query)
```

### Template-based search

#### Method
GET

#### Endpoint
/api/_search-with-template/xm-entities

#### Description
Performs a search using a predefined template and additional parameters.

#### Query Parameters
- **template** (string) - Required - The name of the search template (e.g., "CUSTOMER_SEARCH").
- **(Additional parameters)** - Required/Optional - Parameters specific to the template (e.g., status, region).

#### Response
#### Success Response (200)
- **(Search results based on the template)**

#### Response Example
```json
(Array of search result objects matching the template and parameters)
```

### Search for entities to link

#### Method
GET

#### Endpoint
/api/xm-entities/{entityType}/{entityId}/links/{linkType}/search

#### Description
Searches for entities that can be linked to a specific entity.

#### Path Parameters
- **entityType** (string) - Required - The type of the source entity.
- **entityId** (integer) - Required - The ID of the source entity.
- **linkType** (string) - Required - The type of entities to search for linking.

#### Query Parameters
- **query** (string) - Required - The search query string (e.g., "status:pending").

#### Response
#### Success Response (200)
- **(List of linkable entities)**

#### Response Example
```json
(Array of linkable entity objects)
```
```

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

### Entity Export API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Allows exporting entities by type in various file formats.

```APIDOC
## Entity Export API

### Export entities by type

#### Method
GET

#### Endpoint
/api/export/{entityType}

#### Description
Exports entities of a specified type in a downloadable format (e.g., CSV, Excel).

#### Path Parameters
- **entityType** (string) - Required - The type of entities to export (e.g., "CUSTOMER").

#### Query Parameters
- **format** (string) - Optional - The desired export format (e.g., "csv", "excel"). Defaults to CSV if not specified.

#### Response
#### Success Response (200)
- **(File download)**

#### Response Example
```
(Returns a file download in the specified format)
```
```

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

### Entity State Management API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Enables workflow transitions for entities using a state machine model. Allows updating entity states with optional context data.

```APIDOC
## PUT /api/xm-entities/{id}/states/{stateKey}

### Description
Updates the state of a specific XmEntity and optionally provides context data for the transition.

### Method
PUT

### Endpoint
/api/xm-entities/{id}/states/{stateKey}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the entity whose state needs to be updated.
- **stateKey** (string) - Required - The new state key to transition the entity to.

#### Request Body
- **contextData** (object) - Optional - Additional data to be passed with the state transition (e.g., approval details, notes).
  - **approvedBy** (string) - Example context field.
  - **approvalDate** (string) - Example context field in ISO 8601 format.
  - **notes** (string) - Example context field.

### Request Example
```json
{
  "approvedBy": "admin@example.com",
  "approvalDate": "2024-01-15T14:30:00Z",
  "notes": "All requirements met"
}
```

### Response
#### Success Response (200)
- **id** (integer) - The ID of the updated entity.
- **typeKey** (string) - The type of the entity.
- **stateKey** (string) - The new state key of the entity.
- **name** (string) - The display name of the entity.

#### Response Example
```json
{
  "id": 1,
  "typeKey": "ORDER.PURCHASE",
  "stateKey": "APPROVED",
  "name": "Order #12345"
}
```
```

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

### Links Management API - Create Link

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Creates a new link entity. Requires a JSON payload with link details including typeKey, name, and source/target entity references. An authorization token is mandatory.

```bash
curl -X POST "http://localhost:8080/api/links" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "typeKey": "RELATION.MANAGER",
    "name": "Account Manager",
    "source": {"id": 1},
    "target": {"id": 2}
  }'
```

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

### Profile API

Source: https://context7.com/xm-online/xm-ms-entity/llms.txt

Manages user profiles, allowing retrieval and update of the current user's profile and administrative access to profiles by user key.

```APIDOC
## Profile API Endpoints

### Get current user's profile

#### Method
GET

#### Endpoint
/api/profile

#### Description
Retrieves the profile information for the currently authenticated user.

#### Response
#### Success Response (200)
- **(User profile object)**

#### Response Example
```json
(User profile details)
```

### Update current user's profile

#### Method
PUT

#### Endpoint
/api/profile

#### Description
Updates the profile information for the currently authenticated user.

#### Request Body
- **id** (integer) - Required - The ID of the profile to update.
- **name** (string) - Optional - The updated name for the user.
- **data** (object) - Optional - Additional data for the profile (e.g., preferences).
  - **preferences** (object) - Optional - User preferences.
    - **theme** (string) - Optional - Preferred theme (e.g., "dark").
    - **language** (string) - Optional - Preferred language (e.g., "en").

#### Request Example
```json
{
  "id": 1,
  "name": "Updated Name",
  "data": {
    "preferences": {
      "theme": "dark",
      "language": "en"
    }
  }
}
```

#### Response
#### Success Response (200)
- **(Updated user profile object)**

#### Response Example
```json
(Updated user profile details)
```

### Get profile by user key (admin)

#### Method
GET

#### Endpoint
/api/profile/{userKey}

#### Description
Retrieves a user's profile by their user key (requires administrative privileges).

#### Path Parameters
- **userKey** (string) - Required - The unique key of the user whose profile to retrieve.

#### Response
#### Success Response (200)
- **(User profile object)**

#### Response Example
```json
(User profile details for the specified user key)
```
```
Tokens:
Raw