# Внутреннее API

В рамках работающего процесса, в области видимости каждого коннектора доступен объект `ctx` , который в свою очередь предоставляет доступ к системному API процесса. Данное API позволяет работать внутренними методами процесса, а также управлять workflow.

## Свойства объекта ctx

| Название      | Описание                                                                               |
| ------------- | -------------------------------------------------------------------------------------- |
| ctx.connector | Содержит схему текущего исполняемого коннектора                                        |
| ctx.data      | Содержит данные переданные текущему исполняемому коннектору от предыдущего коннектора. |
| ctx.workplace | Содержит название workplace                                                            |
| ctx.processID | Содержит id текущего процесса                                                          |

## Дополнительные свойства ctx для коннекторов c типом webservice

При выполнении коннекторов с типом webservice объект ctx содержит дополнительные свойства и методы для работы с HTTP запросами.

| Название     | Описание                                                                                |
| ------------ | --------------------------------------------------------------------------------------- |
| ctx.request  | Объект http.request - смотрите документацию [NodeJS](https://nodejs.org/api/http.html)  |
| ctx.response | Объект http.response - смотрите документацию [NodeJS](https://nodejs.org/api/http.html) |

## Основные методы

### ctx.getConnectorId(\<id>)

Метод для получение коннектора процесса по его ID.

{% code title="Connector.code" %}

```javascript
const connector = ctx.getConnectorById("5cb6277d35b3820001a8dbc6");
console.log(connector);

>>> Output >>>
{
    "id": "5cb6277d35b3820001a8dbc6",
    "name": "Expression",
    .......
}
```

{% endcode %}

###

### ctx.stopProcess() - остановка процесса

&#x20;Метод для остановки выполнения процесса.

{% code title="Connector.code" %}

```javascript
(async () => {
    try {
        await ctx.stopProcess();
    } catch (err) {
        console.error(err);
    }
})();
```

{% endcode %}

###

### ctx.setHelper(\<name>, \<any>)

Метод для записи в глобальную область видимости контекста вспомогательных обработчиков.&#x20;

{% code title="Connector.installHandler" %}

```javascript
const getUserById = (id, users) => users.find(user => user.id == id);
ctx.setHelper('getUserById', getUserById);
```

{% endcode %}

После выполнения данного метода в коннекторах будет доступен новый обработчик.

{% code title="Connector.code" %}

```javascript
const user = ctx.getUserById(1, [{id: 1, name: "John Smith"}]);
console.log(user);
```

{% endcode %}

###

### ctx.setData(\<object>)

Метод для установки передаваемых данных между коннекторами через контекст процесса.

{% code title="Connector.code" %}

```javascript
const users = await axios.get("https://domain.com/users");
ctx.setData({
    users: users
});
```

{% endcode %}

*После выполнения данного кода, следующий коннектор может получить массив пользователей от текущего коннектора.*

{% hint style="warning" %}
При использовании метода **setData** в исходящей схеме должны обязательно быть описаны передаваемые данные, иначе они будут проигнорированы.
{% endhint %}

###

### ctx.reject(\<requeue>) - отменить выполнение следующих коннекторов

Метод предназначен для остановки выполнения следующих коннекторов. \
\
Аргумент **requeue**:

* **false** - только отменяет выполнение следующих коннекторов
* **true** - останавливает выполнение следующих коннекторов и ставит выполнение текущего коннектора опять в очередь

*Этот метод может быть полезен например в случаях когда внутри текущего коннектора определяются условия выполнения и если они не отвечают необходимым значениям, то выполняется данный метод, для того чтобы остановить выполнение следующих коннекторов.*

{% code title="Connector.code" %}

```javascript
if (ctx.data.userId !== 1) {
    ctx.reject(false);
}
return Promise.resolve();
```

{% endcode %}

## Методы для работы с DataStorage

### ctx.storage.get(name, params)

Метод предназначен для получения данных их DataStorage.

| Название | Описание                                                                    |
| -------- | --------------------------------------------------------------------------- |
| name     | Название коллекции                                                          |
| params   | Параметры запроса. Подробнее [DataStorage](/untitled.md#datastorage-params) |

{% code title="Connector.code" %}

```javascript
(async () => {
    const users = await ctx.storage.get('users', {
        query: {
            _id: {
                $in: ["5cb6277d35b3820001a8dbc6","5cb6277d35b3820001a8dbc7"]
            }
        },
        limit: 30
    });
    console.log(users);
})();
```

{% endcode %}

### ctx.storage.create(name, params)

Метод предназначен для создания записей в DataStorage

| Название | Описание                                                                    |
| -------- | --------------------------------------------------------------------------- |
| name     | Название коллекции                                                          |
| params   | Параметры запроса. Подробнее [DataStorage](/untitled.md#datastorage-params) |

{% code title="Connector.code" %}

```javascript
(async () => {
    const result = await ctx.storage.create('users', {
        docs: [
            {name: "John Smith", age: 35},
            {name: "Teareza Mayer", age: 28}
        ]
    });
    console.log(result);
})();
```

{% endcode %}

### ctx.storage.update(name, params)

Метод предназначен для обновления записей в DataStorage

| Название | Описание                                                                    |
| -------- | --------------------------------------------------------------------------- |
| name     | Название коллекции                                                          |
| params   | Параметры запроса. Подробнее [DataStorage](/untitled.md#datastorage-params) |

{% code title="Connector.code" %}

```javascript
(async () => {
    const result = await ctx.storage.update('users', {
        query: {
            name: "Teareza Mayer"
        },
        doc: {
            $set: {
                age: 29
            }
        }
    });
    console.log(result);
})();
```

{% endcode %}

### ctx.storage.remove(name, params)

Метод предназначен для удаления записей в DataStorage

| Название | Описание                                                                    |
| -------- | --------------------------------------------------------------------------- |
| name     | Название коллекции                                                          |
| params   | Параметры запроса. Подробнее [DataStorage](/untitled.md#datastorage-params) |

{% code title="Connector.code" %}

```javascript
(async () => {
    const result = await ctx.storage.remove('users', {
        query: {
            name: "Teareza Mayer"
        }
    });
    console.log(result);
})();
```

{% endcode %}

### ctx.storage.count(name, params)

Метод предназначен для подсчета количества записей в DataStorage

| Название | Описание                                                                    |
| -------- | --------------------------------------------------------------------------- |
| name     | Название коллекции                                                          |
| params   | Параметры запроса. Подробнее [DataStorage](/untitled.md#datastorage-params) |

{% code title="Connector.code" %}

```javascript
(async () => {
    const result = await ctx.storage.count('users', {
        query: {
            age: 29    
        }
    });
    console.log(result);
})();
```

{% endcode %}

## Методы для работы с шаблонами процесса

### ctx.setTemplate(name, fn)

Метод позволяющий добавить шаблон в контекст процесса для последующего рендеринга его в вебхуках.

* **name** - название шаблона
* **fn** - функция рендеринга шаблона

{% code title="Connector.code" %}

```javascript
let ejs = require('ejs')
ctx.addTemplate('index_page', ejs.compile(<h1>Hello <%- username %></h1>, {}));
return Promise.resolve();
```

{% endcode %}

### ctx.renderTemplate(name, data)

Метод позволяющий выполнить рендеринг и получить html код предварительно созданного шаблона.

* **name** - название шаблона
* **data** - данные для передачи в шаблон

{% code title="Connector.code" %}

```javascript
(async () => {
    const html = await ctx.renderTemplate('index_page', {
        name: "John Smith"
    });
    
    await ctx.sendMail('user@domain.com', html); // as an example
})();
```

{% endcode %}

## Методы для работы с вебхуками

### ctx.response.json(data)

Метод позволяет ответить на HTTP запрос клиенту в формате json

{% code title="Connector.code" %}

```javascript
(async () => {
    try {
        const userId = ctx.data.params;
        const user = await ctx.storage.get('users', {query: {_id: userId}});
        ctx.response.json(user);
    } catch (err) {
        ctx.response.json({ error: true, code: 500 });
        console.error(err);
    }
})();
```

{% endcode %}

### ctx.response.plain(data)

Метод позволяет ответить на HTTP запрос клиенту в текстовом формате (text/plain)

{% code title="Connector.code" %}

```javascript
(async () => {
    try {
        ctx.response.plain('Hello world');
    } catch (err) {
        ctx.response.plain('Internal error');
        console.error(err);
    }
})();
```

{% endcode %}

### ctx.response.html(data)

Метод позволяет ответить на HTTP запрос клиенту в формате html (text/html)

{% code title="Connector.code" %}

```javascript
(async () => {
    try {
        ctx.response.html('<h1>Hello world</h1>');
    } catch (err) {
        ctx.response.html('<h1>Internal error</h1>');
        console.error(err);
    }
})();
```

{% endcode %}

### ctx.response.render(template, data)

Метод рендерит шаблон и отправляет данные клиенту в формате text/html

* **template** - имя шаблона
* **data** - данные, которые будут переданы в шаблон

{% code title="Connector.code" %}

```javascript
(async () => {
    try {
        ctx.response.render('index_page', {
            name: 'John Smith'
        });
    } catch (err) {
        ctx.response.render('error_page', {
            message: err.message
        });
        console.error(err);
    }
})();
```

{% endcode %}

{% hint style="warning" %}
Для выполнения данного, в контексте процесса должен быть создан шаблон.\
Воспользуйтесь готовыми коннекторами шаблонами (EJS или PUG), либо методами для работы с шаблонами.
{% endhint %}

### ctx.response.redirect(url, code)

Метод позволяет выполнить переадресацию поступившого запроса на другой URL адрес.

* **url** - адрес, куда будет перенаправлен клиент
* **code** - статус код , по умолчанию 301

{% code title="Connector.code" %}

```javascript
(async () => {
    try {
        ctx.response.redirect('https://google.com', 302);
    } catch (err) {
        ctx.response.plain('Internal error');
        console.error(err);
    }
})();
```

{% endcode %}


---

# 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.mixapp.io/processy/vnutrennee-api.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.