Графики (Widgets)
Ресурс Widgets — графическое отображение распределения записей в каталоге по выбранным критериям.

Получить графики

Запрос
Ответ
1
URL: {domain}/api/v1/boards/{boardsId}/widgets
Copied!
Метод: GET
Параметры:
  • boardsId (number) — идентификатор дашборда
Ответ: 200 OK (application/json)
1
[
2
{
3
"id":"14",
4
"name":null,
5
"chartType":"pie",
6
"stacked":null,
7
"value":
8
{
9
"value":"8",
10
"type":"field",
11
"subType":"timeLeft"
12
},
13
"valueFn":"avg",
14
"axis":
15
{
16
"value":"12",
17
"type":"field",
18
"subType":null
19
},
20
"split":null,
21
"recordsType":"available",
22
"recordsFilter":null
23
},
24
{
25
"id":"15",
26
"name":null,
27
"chartType":"columns",
28
"stacked":null,
29
"value":
30
{
31
"value":"",
32
"type":"recordsCount",
33
"subType":null
34
},
35
"valueFn":null,
36
"axis":
37
{
38
"value":"2",
39
"type":"field",
40
"subType":null
41
},
42
"split":
43
{
44
"value":"2",
45
"type":"field",
46
"subType":null
47
},
48
"recordsType":"all",
49
"recordsFilter":null
50
}
51
]
Copied!

Получить график

Запрос
Ответ
1
URL: {domain}/api/v1/boards/{boardsId}/widgets/{widgetsId}
Copied!
Метод: GET
Параметры:
  • boardsId (number) — идентификатор дашборда
  • widgetsId (number) — идентификатор графика
Ответ: 200 OK (application/json)
1
{
2
"id": "14",
3
"name": null,
4
"chartType": "pie", // тип графика
5
"stacked": null, // сложить значения
6
"value": // поле 'Значение'
7
{
8
"type": "field", // тип параметра в поле 'Значение'
9
"value": "8", // id поля
10
"subType": "timeLeft" // обязательный параметр для полей типа: категория, набор галочек, вопрос
11
},
12
"valueFn": "avg", // значение функции
13
"axis": // поле 'Ось'
14
{
15
"type": "field",
16
"value": "12",
17
"subType": null // обязательный параметр для даты создания
18
},
19
"split": null, // поле 'Разложить по' (недоступно для графика типа pie)
20
"recordsType": "available", // доступные записи
21
"recordsFilter": // фильтр
22
{
23
"filters": {
24
"4": // id поля для фильтра
25
[{
26
"recordId": "5",
27
"catalogId": "65"
28
}
29
]
30
}
31
}
32
}
Copied!
Возможные значения:
  • chartType: columns (столбцы), lines (линия), bars (список), pie (пирог), radar (радар), number (число)
  • stacked: true и false
  • value[type]: recordsCount (количество записей), field (поле)
  • value[value]: id поля (если value[type]=field)
  • value[subType]: timeLeft (продолжительность)
  • valueFn: sum (сумма), avg (среднее, не выбранные значения не учитываются), avgAll (среднее по всем, не выбранные значения считаются за ноль), max (максимальное), min (минимальное)
  • axis[type]: field (поле), createdTime (дата создания)
  • axis[value]: id поля (если axis[type]=field)
  • axis[subType]: hour (час), hourOfDay (час дня), day (день), dayOfWeek (день месяца), week (неделя), weekOfYear (неделя года), month (месяц), monthOfYear (месяц года), year (год)
    Подробнее про Ось.
  • split: возможны такие же значения как в axis
  • recordsType: all (все записи каталога), available (только доступные сотруднику записи)

Создать график

Запрос
Ответ
1
URL: {domain}/api/v1/boards/{boardsId}/widgets
Copied!
Метод: POST
Параметры:
  • boardsId (number) — идентификатор дашборда
Запрос: (application/json)
1
{
2
"chartType":"columns",
3
"value":
4
{
5
"type":"recordsCount",
6
"value":null
7
},
8
"valueFn":null,
9
"axis":
10
{
11
"type":"field",
12
"value":"4"
13
},
14
"recordsType":"all"
15
}
Copied!
Ответ: 200 OK (application/json)
1
{
2
"id": "16" // идентификатор созданного графика
3
}
Copied!

Изменить график

Запрос
Ответ
1
URL: {domain}/api/v1/boards/{boardsId}/widgets/{widgetsId}
Copied!
Метод: PATCH
Параметры:
  • boardsId (number) — идентификатор дашборда
  • widgetsId (number) — идентификатор графика
Запрос: (application/json)
1
{
2
"chartType":"columns"
3
}
Copied!
Ответ: 200 OK (application/json)

Удалить график

Запрос
Ответ
1
URL: {domain}/api/v1/boards/{boardsId}/widgets/{widgetsId}
Copied!
Метод: DELETE
Параметры:
  • boardsId (number) — идентификатор дашборда
  • widgetsId (number) — идентификатор графика
Ответ: 200 OK

Значения графика (Values)

Запрос
Ответ

Получить значения распределения графика

1
URL: {domain}/api/v1/boards/{boardsId}/widgets/{widgetsId}/values
2
?recordsFilter[filters][0][fieldId]=12
3
&recordsFilter[filters][0][value][0]=CURRENT_USER
4
&limit=100
5
&offset=0
Copied!
Метод: GET
Параметры:
  • boardsId (number) — идентификатор дашборда
  • widgetsId (number) — идентификатор графика
Параметры фильтра (определяют выборку):
  • value[type] (string) — тип подсчитываемого значения
    • recordsCount — количество найденных записей (по умолчанию)
    • field — значение по полю каталога
  • value[value] (string) — идентификатор поля каталога для расчета. Допустимо указывать поля типов: число, прогресс, звезды, статус, набор галочек, выбор, связанный объект.
  • value[subType] (string) — подтип подсчитываемого значения
    • uniqueCount — подсчет уникальных значений (доступно для полей типа связанная запись, сотрудник, текст)
    • timeLeft — время нахождения записей в определенном значении поля (доступно для полей статус, набор галочек, выбор). Например: сколько записи были в определенных статусах.
    • timeLeft — время до момента перехода в в определенное значении поля (доступно для полей статус, набор галочек, выбор). Например: сколько прошло времени до того как записи перешли в определенный статус.
  • valueFn — применяемая функция для подсчета значений
    • '' (пусто) — не применять никакую функцию (для value[type]=recordsCount)
    • count — количество записей (значений)
    • sum — сумма значений
    • max — максимальное значение в группе
    • min — минимальное значение в группе
    • avg — среднее значение в группе (пустые значения не учитываются)
    • avgAll — среднее значение в группе (пустые значения считаются за 0)
  • axis[type] (string) — тип оси для разложения записей:
    • all — без разложения (значение по умолчанию)
    • field — разложение по полю каталога
    • createdTime — разложение по времени создания записи
  • axis[value] (string) — идентификатор поля оси разложения (для axis[type]=field)
  • axis[subType] (string) — тип группировки данных по оси (для полей типа дата)
    • hour — по часам
    • hourOfDay — по часам дня (все дни «схлопываются»)
    • day — по дням
    • dayOfWeek — по дням недели (пн—вс)
    • week — по неделям
    • weekOfYear — по неделям года (все года «схлопываются»)
    • monthOfYear — по месяцам года (все года «схлопываются»)
    • month — по месяцам
    • year — по годам
  • split[type] (string) — тип разделения (ось 2) значений внутри разложения по оси
    • возможные значения аналогичны параметру axis[type]
  • split[value] (string) — идентификатор поля оси 2 (для split[type]=field)
  • split[subType] (string) — тип группировки данных по оси 2 (для полей типа дата)
    • возможные значения аналогичны параметру axis[subType]
  • splitLimit (число) — если по оси2 вариантов разложения много, то берутся не все, а только часть их них, те которые встречаются чаще (по умолчанию 10, максимум 100)
  • sort (string) — тип сортировки полученной выборки. Для разных типов полей значение по умолчанию разное.
    • axis — сортировать по наименованию (порядку) заголовков осей.
      • Для дат — в порядке их следования
      • Для статусов, наборов галочек, выбора — в порядке указания элементов в поле каталога
      • Для текста, связанных записей, сотрудников — по наименованию
    • value — сортировать по величине значений
  • sortType (string) — направление сортировки полученной выборки
    • asc — по алфавиту / в порядке хронологии / в порядке указания в каталоге
    • desc — в обратном порядке
  • recordsType (string) — какие записи учитывать для подсчета значений
    • all — все записи каталога без проверки прав (доступно, если у сотрудника, делающего запрос есть права на просмотр всех записей каталога)
    • available — учитывать только доступные сотруднику записи каталога
  • recordsFilter (object) — фильтры для выборки записей каталога, такие как filter, sort и другие. подробнее в описании параметров получения записей.
  • limit (number) — количество возвращаемых разложений (по умолчанию 30, максимум 1000)
  • offset (number) — смещение получаемой выборки разложения относительно начала, используется для постраничного получения данных с параметром limit
Естественным языком о смысле параметров описано в статье про интерфейс графика.

Получить значения распределения без создания графика

В версии Бипиума 1.7.1 появился специальный ресурс Values (используйте его). В более ранних версиях используйте метод получения через существующий Дашборд:
1
URL: /{api url}/boards/{boardsId}/widgets/new/values
2
?value[type]=recordsCount
3
&axis[type]=field
4
&axis[value]=2
5
&recordsFilter[filters][0][fieldId]=12
6
&recordsFilter[filters][0][value][0]=CURRENT_USER
7
&limit=100
8
&offset=0
Copied!
Возможные параметры запроса можете найти в параграфе График (Widgets)
Метод: GET
Параметры:
  • boardsId (number) — идентификатор дашборда
Параметры фильтра (определяют выборку):
  • параметры аналогичны параметрам получения значений графика Values
Ответ: 200 OK (application/json)
Пример с наличием разложения по оси (axis):
1
[
2
{
3
"axis": "Анатолий",
4
"values": [
5
{
6
"value": "7"
7
}
8
]
9
},
10
{
11
"axis": "Виктор",
12
"values": [
13
{
14
"value": "4"
15
}
16
]
17
}
18
]
Copied!
Пример с наличием разложения по оси (axis) и оси 2 (split):
1
[
2
{
3
"axis": "Анатолий",
4
"values": [
5
{
6
"split": "1"
7
"value": "3"
8
},
9
{
10
"split": "2"
11
"value": "4"
12
}
13
]
14
},
15
{
16
"axis": "Виктор",
17
"values": [
18
{
19
"split": "2"
20
"value": "3"
21
},
22
{
23
"split": "3"
24
"value": "1"
25
}
26
]
27
}
28
]
Copied!
Параметры:
  • axis — группа распределения, значение может быть строкой или объектом (в зависимости от оси разложения)
  • values (array of objects) — набор значений
    • split — группа разделения (ось 2), значение может быть строкой или объектом (в зависимости от оси разложения)
    • value (number) — значение в группе (ось) с учетом подгруппы если есть (ось 2)

Общие данные графика (Totals)

Запрос
Ответ

Получить общие данные графика

1
URL: /{api url}/boards/{boardsId}/widgets/{widgetsId}/totals
2
?value[type]=recordsCount
3
&axis[type]=field
4
&axis[value]=2
5
&recordsFilter[filters][0][fieldId]=12
6
&recordsFilter[filters][0][value][0]=CURRENT_USER
Copied!
Метод: GET
Параметры:
  • boardsId (number) — идентификатор дашборда
  • widgetsId (number) — идентификатор графика
Параметры фильтра (определяют выборку):
  • Параметры аналогичны параметрам получения значений разложения Values. Игнорируются параметры: sort, sortType, limit, offset.

Получить общие данные без создания графика

В версии Бипиума 1.7.1 появился специальный ресурс Totals (используйте его). В более ранних версиях используйте метод получения через существующий Дашборд:
1
URL: /{api url}/boards/{boardsId}/widgets/new/totals
2
?value[type]=recordsCount
3
&axis[type]=field
4
&axis[value]=2
5
&recordsFilter[filters][0][fieldId]=12
6
&recordsFilter[filters][0][value][0]=CURRENT_USER
Copied!
Метод: GET
Параметры:
  • boardsId (number) — идентификатор дашборда
Параметры фильтра (определяют выборку):
  • Параметры аналогичны параметрам получения значений разложения Values. Игнорируются параметры: sort, sortType, limit, offset.
Ответ: 200 OK (application/json)
1
[{
2
"key": "sum",
3
"value": 1
4
},
5
{
6
"key": "avg",
7
"value": 1
8
},
9
{
10
"key": "count",
11
"value": 1
12
}]
Copied!
Last modified 10mo ago