АПЕКС

Это старая версия документа!

---

В системе пользователям предоставляется возможность не только пользоваться имеющимися возможностями, но и создавать свои собственные инструменты для работы.  Это реализуется путем создания скриптов на Java Script. Ведение самих скриптов выполняется при помощи инструментов справочника”Файлы”, а запуск их производится перетаскиванием из справочника на объекты в системе, или же через контекстное меню, вызываемого по правой кнопке мыши. Чтобы файл воспринимался именно как скрипт, у него должна быть установлена связь «Скрипт».

И конечно содержимое его должно быть именно скриптом. Ниже следует описание работы с ними.

Пользовательский скрипт Пользовательский скрипт должен быть реализован в виде процедуры с именем “userfunc”, которая ничего не возвращает, а на вход принимает переменную “reqData”, представляющую из себя объект, содержащий массив “reqArr”, который в свою очередь содержит объекты системы, состоящие из двух полей: “id” и “type”, где “id” – уникальный идентификатор позиции среди объектов своего типа, а “type” – тип объекта системы. Помимо указанного массива “reqData” содержит свойство “event”, которое изначально имеет значение null, а впоследствии устанавливается пользователем при передаче запроса серверу с целью выбора действия, которое сервер должен произвести над переданными объектами системы. Также “reqData” и каждый из элементов массива “reqArr”, имеют поле с именем “error”, содержащее код ошибки выполнения запроса сервером. Коды ошибок можно найти в приложении к данному руководству. Ниже приведён пример. function userfunc(reqData) {     alert(JSON.stringify(reqData)); }   Данный пользовательский скрипт выведет в браузере сообщение, содержащее объект “reqData”, для объекта(ов) системы, к которому(ым) данный пользовательский скрипт был применён. Ниже приведён пример выводимого таким скриптом сообщения:   {«reqArr»:[{«id»:«21»,«type»:«nomenclature»,«error»:«0»}],«event»:null,«error»:0}   Объект “reqData” предназначен для предоставления пользовательскому скрипту информации о объекте или объектах, к которым он должен быть применён. Также возможна последующая передача данного объекта серверу для выполнения каких-либо действий с объектами системы.   Все необходимые проверки на соответствие/несоответствие входных данных алгоритму пользовательского скрипта должны быть произведены пользователем непосредственно в реализации скрипта.     Запрос серверу Запрос серверу можно осуществить посредством функции “apiDoRequest”. Функция имеет один входной параметр “reqData”, формат которого аналогичен формату данных, передающихся пользовательскому скрипту системой, рассмотренному выше. Данная особенность позволяет без лишних сложностей передавать данные из системы на сервер, попутно внося в них необходимые изменения. Функция возвращает модифицированную переменную “reqData”, массив “reqArr” внутри которой содержит уже не только поля “id” и “type”, но и прочие поля, присущие для данного типа объекта системы. Запрос на чтение данных объекта системы: Для того, чтобы запросить у системы поля одного из объектов, необходимо вызвать функцию “apiDoRequest”, передав ей в виде параметра переменную “reqData” с полем “event” равным “get_data”. Ниже приведён пример переменной “reqData” для запроса полей объекта системы типа «номенклатура» с идентификатором «21». {«reqArr»:[{«id»:«21»,«type»:«nomenclature»,«error»:«0»}],«event»:«get_data»,«error»:0} Массив “reqArr” может содержать неограниченное количество объектов системы разного типа, для которых необходимо осуществить выдачу информации. Пример запроса для нескольких объектов системы указан ниже. {«reqArr»:[{«id»:«21»,«type»:«nomenclature»,«error»:«0»},{«id»:«106»,«type»:«collection»,«error»:«0»},{«id»:«49»,«type»:«nomenclature»,«error»:«0»},{«id»:«745»,«type»:«file»,«error»:«0»}],«event»:«get_data»,«error»:0} Поле “error” в отправляемых данных не играет роли и требует обработки лишь при получении ответа от сервера (сервер отвечает в этом же формате, но добавляет к содержимому элементов массива “reqArr”, помимо полей “id” и “type”, прочие поля, свойственные данному типу объекта системы). Далее приведён пример ответа от сервера на запрос, указанный выше. {«reqArr»:[{«id»:«21»,«type»:«nomenclature»,«name»:«TEST POSITON #1»,«notation»:«NOTATION OF TEST POSITION #1»,«created_date»:«2017-05-28 04:00:09»,«last_change_date»:«2017-05-28 04:00:09»,«error»:«0»}],«event»:«get_data»,«error»:«0»} Процедура пользовательского скрипта, осуществляющего вывод данной JSONстроки в виде сообщения браузера выглядит следующим образом: function userfunc(reqData) {     reqData.event = «get_data»;    alert(JSON.stringify(apiDoRequest(reqData))); }   Запрос на чтение данных объекта системы может быть выполнен для следующих типов объектов системы:  

• Номенклатурная позиция – значение поля “type”:“nomenclature”;
• Коллекция – значение поля “type”:“collection”;
• Файл – значение поля “type”:“file”;
• Параметр – значение поля “type”:“parameter”;
• Компонент – значение поля “type”:“component”;

  Индикация ошибок На случай, если запрос сервера выполнился с некоторыми ошибками, либо не выполнился вовсе, присутствует система кодов ошибок. Если запрос не был выполнен полностью (например, было указано неверное значение поля “event”), сервер возвращает сообщение следующего формата: {«event»:«wrong_event»,«error»:«2»} Значение поля “event” в сообщении такого рода сохраняется от запроса, а поле “reqArr” отсутствует. Если же запрос производился для нескольких объектов системы и для ряда из них он прошёл успешно, а для других – с ошибкой (например, из-за отсутствия прав на чтение), в таком случае сервер возвращает сообщение следующего вида: {«reqArr»:[{«id»:«21»,«type»:«nomenclature»,«name»:«TEST NOMENCLATURE»,«notation»:«ANY NOTATION»,«created_date»:«2017-05-28 04:00:09»,«last_change_date»:«2017-05-28 04:00:09»,«error»:«0»},{«id»:«17»,«type»:«nomenclature»,«error»:«1»}],«event»:«get_data»}   Объекты системы В системе присутствуют следующие типы объектов: · * Номенклатурная позиция;

• · Коллекция;
• · Файл;
• · Параметр;
• · Компонент.

Помимо объектов системы существует система зависимостей, позволяющих подключать к объектам системы ссылки на объекты системы. Возможны следующие типы зависимостей, которые можно создать: · * Компонент*;

• · Связанный параметр;
• · Связанная коллекция;
• · Связанная номенклатура;
• · Связанная зависимость;
• · Связанная ссылка.

* Данный тип зависимости также является объектом системы, но не может существовать сам по себе и обязательно подключается к объекту системы типа «Коллекция», идентификатор которой содержится в поле «parent_obj_id».   Чтение объекта системы Параметр «event» запроса установлен в значение «get_data». Чтение объектов системы может осуществляться по idобъекта и по обозначению объекта в системе. Чтение по обозначению доступно для номенклатуры, параметров и коллекций, но недоступно для компонентов и файлов. Далее приведён запрос на чтение номенклатурной позиции по обозначению. {«reqArr»:[{«type»:«nomenclature»,«name»:«TEST_API_NAME»}],«event»:«get_data»} Сервер возвращает объекты системы в формате JSONстроки со следующей структурой полей: Номенклатурная позиция: · * id– уникальный идентификатор позиции среди объектов своего типа;

• · type– тип объекта (“nomenclature”);
• · name– обозначение позиции (используется вместо «id»);
• · notation– наименование позиции;
• · created_date – дата и время создания позиции;
• · change_date – дата и время изменения позиции;

Коллекция: · * id– уникальный идентификатор позиции среди объектов своего типа;

• · type– тип объекта (“collection”);
• · name– обозначение позиции;
• · notation– наименование позиции;
• · link_type – тип связи позиции;
• · status – статус позиции;
• · start_date – дата начала (формат строки: YYYY-MM-DD);
• · start_time – время начала (формат строки: HH:MM:SS);
• · end_date – дата окончания (формат строки: YYYY-MM-DD);
• · end_time – время окончания (формат строки: HH:MM:SS);
• · created_date – дата и время создания позиции;
• · change_date – дата и время изменения позиции;

Файл: · * id– уникальный идентификатор позиции среди объектов своего типа;

• · type– тип объекта (“file”);
• · name– имя файла;
• · file_type– расширение файла;
• · link_type – тип связи позиции;
• · comment– тип связи позиции;
• · size– размер файла в байтах;
• · created_date – дата и время создания позиции;
• · change_date – дата и время изменения позиции;

Параметр: · * id– уникальный идентификатор позиции среди объектов своего типа;

• · type– тип объекта (“parameter”);
• · name– обозначение позиции;
• · notation– наименование позиции;
• · parameter_type – тип параметра;
• · created_date – дата и время создания позиции;
• · change_date – дата и время изменения позиции;

Компонент: · * id– уникальный идентификатор позиции среди объектов своего типа;

• · type– тип объекта (“component”);
• · nomenclature_id – идентификатор номенклатурной позиции, на базе которой был создан компонент;
• · parent_obj_id – идентификатор коллекции в которой содержится данный компонент;
• · parent_id – идентификатор родительского объекта типа «компонент» в дереве компонентов;
• · link_type – тип связи позиции;
• · status – статус позиции;
• · amount – количество;
• · unit – единица измерения;
• · comment – комментарий;
• · price – цена;
• · start_date – дата начала (формат строки: YYYY-MM-DD);
• · start_time – время начала (формат строки: HH:MM:SS);
• · end_date – дата окончания (формат строки: YYYY-MM-DD);
• · end_time – время окончания (формат строки: HH:MM:SS);
• · created_date – дата и время создания позиции;
• · change_date – дата и время изменения позиции;

·   Чтение содержимого блоков объекта Параметр «event» запроса установлен в значение «get_obj_blocks». Сервер возвращает содержимое блоков объекта системы в формате JSONстроки. Тело запроса для объекта состоит из двух полей * type– тип объекта;

• · id – id объекта;

Далее приведён запрос на чтение всех блоков коллекции. {«reqArr»:[{«id»:55092,«type»:«collection»}],«event»:«get_obj_blocks»} Далее приведён ответ сервера на на чтение всех блоков коллекции. {«reqArr»:[{«id»:55092,«type»:«collection»,«blocks»:{«linked_components»:[{«id»:«510724»,«nomenclature_id»:«102020»,«parent_id»:«0»,«link_type»:«68»,«status»:«11»,«amount»:«234»,«unit»:«27»,«comment»:«test1»,«price»:«55.00»,«start_date»:«2019-04-03»,«start_time»:«08:23:26»,«end_date»:«2019-04-03»,«end_time»:«08:23:26»,«nomenclature_name»:«TEST NOMENCLATURE»,«nomenclature_notation»:«NOTATION»,«link_type_name»:«Заказ»,«status_name»:«Завершено»,«unit_name»:«шт.»}],«linked_parameters»:[{«id»:«4750»,«param_id»:«291»,«parent_id»:«0»,«s_value»:«»,«d_value»:«34534»,«param_name»:«TEST PARAM 1»,«param_notation»:«TEST1»,«param_type»:«Float»}],«linked_files»:[{«id»:«52546»,«file_id»:«3029»,«file_name»:«test.jpg»,«file_type»:«jpg»,«file_size»:«15012»,«file_link_type»:«0»,«file_comment»:«»,«link_typy_name»:«»}],«linked_links»:[{«id»:«141»,«link»:«https://yandex.ru/»,«comment»:«88—-»}],«linked_collections»:[{«id»:«125932»,«collection_id»:«55096»,«collection_name»:«NEW_TEST_API_COLLECTION»,«collection_notation»:«NOTATION»,«collection_link_type»:«34»,«collection_status»:«11»,«collection_start_date»:«2019-05-09»,«collection_start_time»:«03:15:00»,«collection_end_date»:«2019-05-16»,«collection_end_time»:«04:15:00»,«link_type_name»:«Операция»,«status_name»:«Завершено»}],«linked_nomenclature»:[{«id»:«16249»,«nomenclature_id»:«102020»,«link_type»:«0»,«comment»:«»,«nomenclature_name»:«TEST NOMENCLATURE»,«nomenclature_notation»:«NOTATION»,«link_type_name»:«»}]}}],«event»:«get_obj_blocks»,«error»:0}   Чтение содержимого блока компонентов коллекции с учётом фильтрации Параметр «event» запроса установлен в значение «get_components_filter». Сервер возвращает содержимое блока компонентов коллекции с учётом фильтрации в формате JSONстроки в формате аналогичном запросу «get_obj_blocks». Для осуществления фильтрации могут быть использованы следующие параметры: · * Номенклатура, на базе которой созданы компоненты;

• · Единица измерения компонента;
• · Массив прикреплённых к компоненту параметров и соответствующие им значения;

Тело запроса для объекта состоит из двух полей · * type– тип объекта (должен быть установлен в «collection»);

• · id – id коллекции;
• · name– обозначение коллекции (используется вместо «id»);
• · nomenclature_id– idноменклатуры, на базе которой должны быть созданы отобранные компоненты;
• · nomenclature_name – обозначение номенклатуры, на базе которой должны быть созданы отобранные компоненты (используется вместо «nomenclature_id»);

· * unit_id – idединицы измерения для отбора компонентов;

• · unit_name – обозначение единицы измерения для отбора компонентов (используется вместо «unit_id»);
• · params– массив параметров и их значений, которые должны быть прикреплены к компоненту для попадания в выборку (имеет следующий вид: [{«Параметр_1»:«Значение »},{«Параметр_2»:« Значение»},…,{«Параметр_N»:« Значениe»}]);

Далее приведён запрос на чтение компонентов коллекции с учётом следующих фильтров: · * Родительская коллекция с обозначением «Тестовая коллекция»;

• · Номенклатура, на базе которой созданы компоненты, должна иметь обозначение «Тестовая номенклатура»;
• · Единица измерения компонента «кг»;
• · Компонента должна иметь два прикреплённых параметра «Тестовый параметр 1» и «Тестовый параметр 2» со значениями «123» и «456» соответственно;

{«reqArr»:[{«type»:«collection», «name»:«Тестовая коллекция»,«nomenclature_name»:«Тестовая номенклатура», «unit_name»:«кг»,«params»:[{«Тестовый параметр 1»:«123»},{«Тестовый параметр 2»:«456»}]}],«event»:«get_components_filter»}   Редактирование объекта системы Параметр «event» запроса установлен в значение «edit_data». Сервер осуществляет редактирование выбранного объекта системы Тело запроса для объекта состоит из трёх и более полей (в зависимости от количество реквизитов объекта, которые необходимо отредактировать) · * type– тип объекта;

• · id – id объекта;
• · name– обозначение объекта (используется вместо «id»);
• · <поле_объекта 1> – любое из полей объекта, доступное для редактирования;
• · <поле_объекта 2> – любое из полей объекта, доступное для редактирования;
• · <поле_объекта N> – любое из полей объекта, доступное для редактирования;

Далее приведён запрос для редактирования поля количества у компонента с idравным «256486», количество для этого компонента будет установлено в «123». {«reqArr»:[{«type»:«component»,«id»:«256486»,«amount»:«123» }],«event»:«edit_data»}   Удаление объекта системы Параметр «event» запроса установлен в значение «delete_data». Сервер осуществляет удаление выбранного объекта системы Тело запроса для объекта состоит из двух полей: · * type– тип объекта;

• · id – id объекта;
• · name– обозначение объекта (используется вместо «id»);

Далее приведён запрос для удаления номенклатурной позиции с idравным «21». {«reqArr»:[{«id»:«21»,«type»:«nomenclature»}],«event»:« delete_data» }   Чтение доступных статусов Параметр «event» запроса установлен в значение «get_statuses».   Чтение доступных единиц измерения Параметр «event» запроса установлен в значение «get_units».   Чтение доступных типов связи Параметр «event» запроса установлен в значение «get_link_types».   Запись данных Параметр «event» запроса установлен в значение «new_data». В ответ на запрос записи сервер отправляет JSON структуру с подтверждением, содержащую идентификаторы вновь созданных объектов. Далее приведён запрос на создание номенклатурной позиции. {«reqArr»:[{«type»:«nomenclature»,«name»:«TEST_API_NOM_NAME»,«notation»:«TEST_API_NOM_NOTATION»,«folder_name»:«test_api_folder»}],«event»:«new_data»} Далее приведён ответ сервера на создание номенклатурной позиции. {«reqArr»:[{«type»:«nomenclature»,«name»:«TEST_API_NOM_NAME»,«notation»:«TEST_API_NOM_NOTATION»,«folder_name»:«test_api_folder»,«error»:0,«id»:102024}],«event»:«new_data»,«error»:0} Для записи данных необходимо отправить данные в следующем формате: Номенклатурная позиция: · * name - обозначение новой позиции;

• · notation - наименование новой позиции;
• · folder_name - наименование каталога во «Входящие», в который будет помещена пользовательская ссылка на позицию;

Коллекция: · * name – обозначение позиции;

• · notation – наименование позиции;
• · link_type – тип связи позиции;
• · status – статус позиции;
• · start_date – дата начала (формат строки: YYYY-MM-DD);
• · start_time – время начала (формат строки: HH:MM:SS);
• · end_date – дата окончания (формат строки: YYYY-MM-DD);
• · end_time – время окончания (формат строки: HH:MM:SS);
• · folder_name - наименование каталога во «Входящие»

Параметр: · * name - обозначение новой позиции

• · notation - наименование новой позиции
• · folder_name - наименование каталога во «Входящие»
• · parameter_type - тип параметра. Значения «Float» или «Text»

Файл: Запись файлов в систему посредством APIна текущий момент недоступна. Компонент: · * nomenclature_id – идентификатор номенклатурной позиции, на базе которой будет создан компонент;

• · parent_obj_id – идентификатор коллекции в которой будет создан данный компонент;
• · parent_id – идентификатор родительского объекта типа «компонент» в дереве компонентов;
• · link_type – тип связи позиции;
• · status – статус позиции;
• · amount – количество;
• · unit – единица измерения;
• · comment – комментарий;
• · price – цена;
• · start_date – дата начала (формат строки: YYYY-MM-DD);
• · start_time – время начала (формат строки: HH:MM:SS);
• · end_date – дата окончания (формат строки: YYYY-MM-DD);
• · end_time – время окончания (формат строки: HH:MM:SS);
•  

Связанный параметр: · * parameter_id - id параметра в системе;

• · parent_obj_id - id родительского объекта (коллекции, компонента и т.д.);
• · parent_obj_type - тип родительского объекта (nomenclature, collection, file, component);
• · parent_id - id родительского прикреплённого параметра для организации иерархии. 0 - для помещения в корень;
• · s_value - строковое значение для строковых параметров;
• · d_value - числовое значение для числовых параметров;

Связанная коллекция: · * collection_id - id коллекции в системе;

• · parent_obj_id - id родительского объекта (коллекции, компонента и т.д.);
• · parent_obj_type - типродительскогообъекта (nomenclature, collection, file, component);
• · assignment_link_type – назначение позиции (тип связи);

Связанная номенклатура: · * nomenclature_id - id номенклатуры в системе;

• · parent_obj_id - id родительского объекта (коллекции, компонента и т.д.);
• · parent_obj_type - типродительскогообъекта (nomenclature, collection, file, component);
• · comment – комментарий;
• · link_type – тип связи позиции;

Связанная зависимость: · * component_id - id компонента в системе;

• · parent_obj_id - id родительского объекта (коллекции, компонента и т.д.);
• · assignment_link_type – назначение позиции (тип связи);

Связанная ссылка: · * link – текст ссылки;

• · parent_obj_id - id родительского объекта (коллекции, компонента и т.д.);
• · parent_obj_type - типродительскогообъекта (nomenclature, collection, file, component);
• · comment – комментарий.

Коды ошибок 0 – Ошибки отсутствуют; 1 – Ошибка прав; 2 – Ошибка получения данных; 3 – Ошибка данных запроса; 4 – Ошибка создания позиции; 5 – Ошибка авторизации; 6 – Ошибка подписки.