# MongoDB Adapter

## Getting Started

* Host, port, authentication database and database must be configured (authentication database and database can be equal)
* Username and password must be provided (anonymous usage is not supported)
* Class mapping keys for root documents must always start with the collection name: 
* Class mapping keys for nested arrays must include the nested path prefixed by a $: **$**
* Class mapping keys for multiple nested arrays must be separated by a #: **$#**
* Nested paths cannot be skips, thus for a double nested array three classes must exist (root, nested and nested in nested)
* Field mapping keys must always be relative:  (for root documents and nested arrays)
* Field mapping keys for nested documents must be separated by a dot **.**
* Field mapping keys for parent fields must be absolute prefixed with by a $: **$**
* Field mapping data types must match (see data types for more)
* ID fields as identity must be present for all classes (must be unique; can be any data type)
* Parent fields must be present for nested arrays and should be identical to the parent class ID field
* Parent fields should be read-only (there will not be updated or inserted anyway)

### Data types

(see <https://docs.mongodb.com/manual/reference/bson-types/> for more)

| Platform/Source | other | double  | string | objectId | bool  | date  | int     | long    | decimal |
| --------------- | ----- | ------- | ------ | -------- | ----- | ----- | ------- | ------- | ------- |
| Other           | Error | Error   | Error  | Error    | Error | Error | Error   | Error   | Error   |
| Guid            | Error | Error   | Parse  | Error    | Error | Error | Error   | Error   | Error   |
| Boolean         | Error | Error   | Parse  | Error    | Value | Error | Error   | Error   | Error   |
| String          | Error | Parse   | Value  | Parse    | Parse | Parse | Parse   | Parse   | Parse   |
| DateTime        | Error | Error   | Parse  | Error    | Error | Value | Error   | Error   | Error   |
| Integer         | Error | Value\* | Parse  | Error    | Error | Error | Value   | Value\* | Value\* |
| Byte            | Error | Value\* | Parse  | Error    | Error | Error | Value\* | Value\* | Value\* |
| Short           | Error | Value\* | Parse  | Error    | Error | Error | Value\* | Value\* | Value\* |
| Long            | Error | Value\* | Parse  | Error    | Error | Error | Value\* | Value   | Value\* |
| Float           | Error | Value\* | Parse  | Error    | Error | Error | Value\* | Value\* | Value\* |
| Double          | Error | Value   | Parse  | Error    | Error | Error | Value\* | Value\* | Value\* |
| Numeric         | Error | Value\* | Parse  | Error    | Error | Error | Value\* | Value\* | Value   |
| Char            | Error | Value\* | Parse  | Error    | Error | Error | Value   | Value\* | Value\* |

* Value  = value used
* Value\* = value used, fails on data loss
* Parse  = string parsed, fails on format error
* Error  = fails always

### Examples:

Class "Project" mapped to "projects" with the following fields:

| Platform key | Platform type | Source key   | Source type | Other    |
| ------------ | ------------- | ------------ | ----------- | -------- |
| ID           | String        | \_id         | objectId    | identity |
| Title        | String        | title        | string      |          |
| Start        | DateTime      | period.start | date        |          |
| End          | DateTime      | period.end   | date        |          |

Class "Task" mapped to "projects$tasks" with the following fields:

| Platform key  | Platform type | Source key    | Source type | Other     |
| ------------- | ------------- | ------------- | ----------- | --------- |
| ID            | String        | \_id          | objectId    | identity  |
| ParentID      | String        | $\_id         | objectId    | read-only |
| Title         | String        | title         | string      |           |
| Description   | String        | description   | string      |           |
| RemainingWork | Integer       | remainingWork | int         |           |

Class "Comment" mapped to "projects$tasks#comments" with the following fields:

| Platform key | Platform type | Source key  | Source type | Other     |
| ------------ | ------------- | ----------- | ----------- | --------- |
| ID           | String        | \_id        | objectId    | identity  |
| ParentID     | String        | $tasks.\_id | objectId    | read-only |
| Content      | String        | content     | string      |           |

Sample document in collection "projects":

```javascript
{
  "_id": { "$oid": "5fcd1c3c1f028fce28332d9d" },
  "title": "Project1",
  "period": {
    "start": { "$date": "2020-12-16T00:00:00.000+00:00" },
    "end": { "$date": "2020-12-17T00:00:00.000+00:00" }
  },
  "tasks": [
    {
      "_id": { "$oid": "5fcd1c3c1f028fce28332d9d" },
      "title": "Task1",
      "description": "Description of Task1",
      "remainingWork": 8,
      "comments": [
        {
          "_id": { "$oid": "5fcd2b466b0df14c8839d04d" },
          "content": "Content1"
        }
      ]
    }
  ]
}
```

## Capabilities

### Authentication

* User will be authenticated to the authentication database configured
* The connection string is entered directly. The connection string must not contain the credentials and the step must mention that the credentials will be added by the adapter.

### Data

* Documents will not be inserted through create, but through update new
* All read methods are not implemented, since they are not used when the query capability is present
* Insert, update and delete differs heavily between root documents and nested arrays
* To effectively manage CRUD operations a special mapping is provided
* Data times will be converted to local culture (MongoDB saves them always as UTC)

### Query

* The logical operator `And` takes priority over `Or` in execution order
* Condition values are given as strings and thus converted using the local culture


---

# 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.tivity.one/extensibility-and-integration/adapter-portfolio/mongodb-adapter.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.