Графики (Widgets)

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

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

Запрос

URL: {domain}/api/v1/boards/{boardsId}/widgets

Метод: GET

Параметры:

• boardsId (number) — идентификатор дашборда

Ответ

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

Запрос

URL: {domain}/api/v1/boards/{boardsId}/widgets/{widgetsId}

Метод: GET

Параметры:

• boardsId (number) — идентификатор дашборда

• widgetsId (number) — идентификатор графика

Ответ

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

Запрос

URL: {domain}/api/v1/boards/{boardsId}/widgets

Метод: POST

Параметры:

• boardsId (number) — идентификатор дашборда

Запрос: (application/json)

        {
            "chartType":"columns",
            "value":
                {
                    "type":"recordsCount",
                    "value":null
                },
            "valueFn":null,
            "axis":
                {
                    "type":"field",
                    "value":"4"
                },
            "recordsType":"all"
        }

Ответ

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

Запрос

URL: {domain}/api/v1/boards/{boardsId}/widgets/{widgetsId}

Метод: PATCH

Параметры:

• boardsId (number) — идентификатор дашборда

• widgetsId (number) — идентификатор графика

Запрос: (application/json)

{
    "chartType":"columns"
}

Ответ

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

Запрос

URL: {domain}/api/v1/boards/{boardsId}/widgets/{widgetsId}

Метод: DELETE

Параметры:

• boardsId (number) — идентификатор дашборда

• widgetsId (number) — идентификатор графика

Ответ

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

Запрос

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

URL: {domain}/api/v1/boards/{boardsId}/widgets/{widgetsId}/values
            ?recordsFilter[filters][0][fieldId]=12
            &recordsFilter[filters][0][value][0]=CURRENT_USER
            &limit=100
            &offset=0

Метод: 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 (используйте его). В более ранних версиях используйте метод получения через существующий Дашборд:

URL: /{api url}/boards/{boardsId}/widgets/new/values
            ?value[type]=recordsCount
            &axis[type]=field
            &axis[value]=2
            &recordsFilter[filters][0][fieldId]=12
            &recordsFilter[filters][0][value][0]=CURRENT_USER
            &limit=100
            &offset=0

Возможные параметры запроса можете найти в параграфе График (Widgets)

Метод: GET

Параметры:

• boardsId (number) — идентификатор дашборда

Параметры фильтра (определяют выборку):

• параметры аналогичны параметрам получения значений графика Values

Ответ

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

Запрос

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

URL: /{api url}/boards/{boardsId}/widgets/{widgetsId}/totals
            ?value[type]=recordsCount
            &axis[type]=field
            &axis[value]=2
            &recordsFilter[filters][0][fieldId]=12
            &recordsFilter[filters][0][value][0]=CURRENT_USER

Метод: GET

Параметры:

• boardsId (number) — идентификатор дашборда

• widgetsId (number) — идентификатор графика

Параметры фильтра (определяют выборку):

• Параметры аналогичны параметрам получения значений разложения Values. Игнорируются параметры: sort, sortType, limit, offset.

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

В версии Бипиума 1.7.1 появился специальный ресурс Totals (используйте его). В более ранних версиях используйте метод получения через существующий Дашборд:

URL: /{api url}/boards/{boardsId}/widgets/new/totals
            ?value[type]=recordsCount
            &axis[type]=field
            &axis[value]=2
            &recordsFilter[filters][0][fieldId]=12
            &recordsFilter[filters][0][value][0]=CURRENT_USER

Метод: GET

Параметры:

• boardsId (number) — идентификатор дашборда

Параметры фильтра (определяют выборку):

• Параметры аналогичны параметрам получения значений разложения Values. Игнорируются параметры: sort, sortType, limit, offset.

Ответ