# Внутреннее 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](https://docs.mixapp.io/untitled#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](https://docs.mixapp.io/untitled#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](https://docs.mixapp.io/untitled#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](https://docs.mixapp.io/untitled#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](https://docs.mixapp.io/untitled#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 %}