API версии 5

Ваш путеводитель по интеграции V5!

Введение

Шлюз V5 Traceability Gateway обеспечивает двунаправленный обмен данными между линейкой продуктов V5 Traceability и другими решениями. Шлюз обладает высокой гибкостью, обеспечивая быстрое развертывание множества различных ERP-систем и внешних систем, что позволяет клиентам эффективно интегрировать все предприятие. Ассортимент продуктов V5 имеет обширный API для интеграции.

В этом руководстве представлен подробный обзор того, как использовать различные методы импорта и экспорта данных. Он также подробно описывает каждый объект, который можно импортировать, и возможные поля для этих объектов.

Ворота можно использовать двумя основными способами:

Через REST API веб-интерфейса с использованием файлов JSON или XML.
Через прямой обмен файлами с документами CSV или XML.

Оба эти метода будут рассмотрены в этом руководстве, а также приведены примеры для основных областей интеграции данных.

1. Что делает шлюз V5?

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

В зависимости от требований заказчика, V5 Traceability можно настроить для интеграции любого количества областей, таких как рецептуры/ведомости материалов, планирование работ, заказы на покупку и продажу, а также уровни и местонахождение запасов.

2. Пример диаграммы потока данных

На приведенной ниже диаграмме потока данных показана бесшовная интеграция хост-системы ERP и V5 Traceability. От получения и управления запасами до составления партий, создания продукта, комплектации заказов на продажу и отгрузки. V5 Gateway позволяет предприятиям эффективно оптимизировать свои операции, повышая прозрачность производства и устраняя ошибки в процессе отслеживания.

3. Руководства по интеграции

В этом разделе вы можете найти конкретные руководства по интеграции определенных модулей прослеживаемости V5:

Для основных модулей, которые обычно имеют двухстороннюю интеграцию:

Для второстепенных модулей, которые поддерживают только параметры импорта:

Для получения помощи в установке и обновлении API V5 обратитесь к следующей документации:

Руководство по установке и обновлению API V5

Примеры развертывания интеграции см. в наших руководствах по конкретным ERP-решениям ниже:

4. Справочные документы по интеграции V5

В этом руководстве по методам интеграции V5 Traceability мы будем регулярно использовать две части документации, которые помогут нам. Оба они полезны независимо от метода интеграции, который мы используем. Это:

Рабочий лист интеграции V5 который содержит полезную информацию и шаблоны для наиболее часто интегрируемых модулей.
Руководство по API V5, который можно использовать для определения конкретных URI импорта/экспорта, а также предоставляет подробное руководство по каждому классу данных, используемому API V5.
В руководствах по API в этом разделе будут ссылки на конечные точки транзакций и журналов. Полный их список можно найти, пройдя по ссылке.

5. Методология — V5 API

Если использовать этот метод, то API V5 будет установлен в качестве веб -службы для облегчения передачи данных. Отсюда транзакции обрабатываются различными доступными классами модуля.

Чтобы узнать больше об этих классах, различных конечных точках/URI, а также информацию о различных классах баз данных, с которыми мы будем иметь дело при использовании V5 API, мы можем использовать как 'Рабочий лист сопоставления интеграции V5и Веб-сайт API V5 помочь нам. Отсюда мы можем использовать проводник пакетов в левом верхнем углу этого окна для навигации по различным разделам руководства по API.

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

После установки к конечным точкам API можно получить доступ через браузер или клиент REST по адресу:

http://{hostname:port}/V5-API/api

Модуль IntegrationImport имеет путь /integrate/import/

Модуль IntegrationExport имеет путь /integrate/export/

Путь к модулю «Транзакции» /integrate/export/transactions/

Каждый метод имеет свой собственный путь, указанный в каталоге API V5 в виде файла. ‘Target URI’. Его можно добавить в конец вышеуказанных путей, чтобы выполнить метод.

Каждое описание метода также содержит ‘request type’, который указывает, является ли это запросом GET или POST, а также URI для данного метода.

Любые запросы на получение или публикацию будут обработаны в формате JSON. Все поля и объекты определены в пакете базы данных, которые вы можете найти через пакет услуг.

5.1. Экспорт/GET-запросы

Как упоминалось выше, модуль экспорта V5 API имеет путь:

http://{hostname:port}/V5-API/api/integrate/export/

Так что на самом деле это будет выглядеть примерно так (при взаимодействии через локально установленный экземпляр V5 API):

http://127.0.0.1:8080/V5-API/api/integrate/export/

Что последует за этим, зависит от того, какие данные мы хотим извлечь из V5. Затем мы обратились бы к пакету услуг, используя окна слева от главного окна API, чтобы выбрать пакет услуг, а затем «IntegrationExport» ниже.

Мы также можем использовать ссылку на услуги на странице индекса, которая затем загрузит сводку класса для этого пакета, где мы затем можем выбрать класс «IntegrationExport».

Затем нам будет показан целевой URI экспорта (1) вместе со списком доступных конечных точек для класса модуля экспорта. Мы можем просмотреть все это подробно, щелкнув конструктор «IntegrationExport» (2), или мы можем использовать ‘Method Summary’ таблицу ниже (3), чтобы быстро найти нужную конечную точку. Мы также можем увидеть целевой URI для этого модуля вверху страницы, поэтому все, что нам нужно сделать сейчас, — это определить необходимые объекты, поля и значения.

Итак, давайте возьмем здесь первую запись в сводной таблице методов: ‘Batch’. Щелчок по ссылке в правом столбце (4) приведет нас прямо к конечной точке, о которой мы хотим узнать.

Это дает нам необходимую информацию, в том числе данные, которые будут отозваны, тип запроса и, самое главное, целевой URI для запроса.

Итак, теперь мы знаем, что если мы хотим получить пакет из API V5, конечная точка, которую нам нужно будет нажать, будет:

http://127.0.0.1:8080/V5-API/api/integrate/export/batch/{batchNumber}

Давайте быстро посмотрим, как это будет работать на практике. Мы можем начать с поиска пакета, который мы хотим получить через API, давайте перейдем к пакету «50009622», который мы можем видеть здесь в Центр управления.

Используя то, что мы узнали выше, мы можем затем заполнить URI в клиенте REST как таковой:

Запуск этого процесса сейчас приведет к созданию подробного файла JSON для этого пакета, который затем может быть использован и проанализирован клиентским приложением. Типичный возврат для этого запроса может выглядеть следующим образом.

Во многих случаях, когда плюрализм применим к конечным точкам, к которым мы обращаемся (например, здесь пакет может стать пакетом), мы можем использовать это для вызова списка пакетов с помощью ‘export/batches’ URI.

5.2. Импорт/POST-запросы

Как упоминалось выше, модуль импорта API V5 имеет путь:

http://{hostname:port}/V5-API/api/integrate/import/

Что последует за этим, будет зависеть от того, какие данные мы хотим импортировать через API. Вернемся к разделу пакетов услуг Руководство по API и на этот раз нажмите «IntegrationImport» (1).

Это расположено таким же образом на странице экспорта, с URI импорта (2), ссылкой на верхнюю часть сводных страниц ниже (3) и сводной таблицей методов (4), где мы можем видеть все доступные конечные точки. .

Как и раньше, нам просто нужно найти конечную точку, относящуюся к данным, которые мы хотим отправить в систему через API.

Обратите внимание, что большинство конечных точек импорта POST ожидают массив, поэтому в одном запросе можно отправить несколько записей. В этом можно убедиться, посмотрев на типы параметров для конечных точек импорта в разделе ‘Method Summary’.

Возьмем в качестве примера товары:

Здесь это говорит нам о том, что мы можем использовать эту конечную точку для импорта списков товаров/ингредиентов, которые затем можно использовать для рецептуры. URI, который мы будем использовать для этого, будет следующим:

http://127.0.0.1:8080/V5-API/api/integrate/import/commodity

Мы можем увидеть эту конечную точку в использовании ниже вместе с очень простым образцом файла импорта в формате JSON:

Чтобы помочь нам в структурировании файла импорта JSON, мы можем использовать ссылку на соответствующий раздел пакетов баз данных в руководстве по API, представленный в сводке службы:

Или мы можем вручную перейти к соответствующему разделу, выбрав раздел сводки класса базы данных из Домашняя страница API.

Если мы перейдем на страницу класса базы данных ниже для ‘Commodity’, мы можем, как нам следует структурировать файл JSON. Например, если мы хотим определить код товара при использовании этого URI, это будет ‘code’, и аналогично для описания товара это будет ‘description’.

Обратите внимание, что эти поля расположены в самом левом углу приведенного выше примера файла JSON вместе с другими полями, которые мы видим на снимке экрана, например: ‘defExpiryDays’. Мы также могли бы добавить в наш файл стоимость товара по умолчанию, и, проверив ниже, мы видим, что это будет просто ‘cost’ (1). Также обратите внимание, что все, что указано здесь как ‘primary key’ (2) является обязательным полем для этой конечной точки, т. е. файл не будет импортирован, если оно отсутствует.

Мы также можем просматривать различные уровни API из этого класса базы данных, поэтому давайте посмотрим, как мы можем это сделать, чтобы включить больше информации о наших товарах. ‘units’.

Внизу этой страницы мы встретим ‘WeightUnit’, который мы можем использовать как вложенный класс в URI товара.

Это дает нам класс базы данных для ‘units’, который может находиться на том же уровне, что и другие классы, которые мы уже определили. Чтобы узнать, какие данные мы можем вложить сюда, мы можем нажать на ‘WeightUnit’ здесь, чтобы просмотреть определения этого класса.

Как мы видим, в этом классе есть только 3 точки данных, и в нашем примере JSON мы используем их все: ‘code’, ‘description’, и ‘conversionRate’. Эти 3 точки данных будут вложены в ‘units’ поле, как показано.

Если мы запустим этот файл JSON, как указано выше, мы (в зависимости от используемого клиента) увидим ответ от API, а также сможем увидеть этот товар, импортированный в наш 'Сырьевые товары' в Центре управления.

5.3. Вставить или обновить?

При использовании функции POST для обращения к конечным точкам API V5 это может либо обновить, либо вставить запись. То, что здесь происходит, определяется первичным ключом, который мы пытаемся опубликовать.

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

И наоборот, если код в настоящее время не существует в базе данных V5, будет создана новая запись.

Однако, если мы посмотрим на нашу ‘units’ вложенном классе, обратите внимание, что, хотя мы можем вставлять новые данные модуля, если первичный ключ этого класса еще не существует, мы не можем обновлять существующие модули, используя ‘commodity’ конечная точка. Вместо этого нам пришлось бы обратиться к ‘import/unit’ Вместо этого URI.

5.4. Экспорт маркеров

V5 API использует маркеры экспорта, чтобы различать данные, которые уже были или еще не были экспортированы в систему ERP клиента. По умолчанию это включено, чтобы помочь экспортировать данные, которые внешняя ERP еще не видела, и после того, как они будут помечены как экспортированные в базе данных V5, эти данные не будут включены в будущий экспорт.

Однако это может быть отключено в зависимости от предпочтений клиента. Это также можно отключить, если используемая система ERP может возвращать маркеры экспорта в V5 API, чтобы подтвердить, что она уже получила рассматриваемые данные.

В этой ситуации подтверждение получения используется для информирования API V5 о том, что данные были получены; конечная точка, которая может использоваться для контроля этого, документирована. здесь.

Если ни V5 API, ни ERP не настроены на предоставление маркеров экспорта, то в зависимости от используемой конечной точки потенциально может возвращаться огромное количество данных. В этих случаях мы можем использовать параметры URI для фильтрации объема экспортируемых данных.

5.5. Параметры URI

V5 API также использует различные параметры URI, которые можно использовать для дальнейшего сужения запросов от системы.

Мы можем увидеть, доступны ли эти параметры для наших конечных точек, проверив сводку методов в желаемой службе. Если мы сможем увидеть ‘int’ за которым следует параметр, то мы можем использовать этот параметр для фильтрации результатов, которые мы получим обратно от API.

Например, мы видели выше, что это работает для ‘batch’ позволяя нам фильтровать по номеру партии.

Другие примеры могут включать в себя получение пакетных журналов по дате, где мы можем использовать ‘batch_system_logs/filterFrom/{filterDate}’ (с использованием соглашений о датировке эпох).

5.6. Журналы, транзакции и системные дескрипторы

Для многих модулей, которые можно интегрировать через API V5, зачастую удобнее получать информацию из конечных точек транзакций и журналов. Некоторые из них можно использовать для нескольких целей (например, «системные журналы»), тогда как другие более адаптированы для конкретных модулей (например, «транзакции продаж»).

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

Чтобы просмотреть эти конечные точки и какую информацию они возвращают/для каких модулей они полезны, нажмите здесь.

6. Методология — общий доступ к CSV-файлам

Метод совместного использования файлов V5 использует файлы CSV и CSVH «заголовок» для выполнения обмена данными с прослеживаемостью V5. Для этих обменов мы будем использовать файлы «заголовков», чтобы определить порядок данных как для импорта, так и для экспорта, а затем мы либо импортируем, либо получаем экспортированный csv, который следует этому порядку. Мы можем взглянуть на то, как это будет работать на практике ниже.

6.1. Порядок файлов данных и заголовков

Независимо от того, импортируем ли мы данные или экспортируем их с помощью метода обмена CSV-файлами, мы будем использовать файлы заголовков для определения порядка данных. С точки зрения того, как мы можем их структурировать, здесь мы можем использовать как 'Рабочий лист сопоставления интеграции V5' и онлайн Руководство по API чтобы помочь нам в этом. Давайте посмотрим на пример здесь для ‘Commodities’ импортировать из рабочего листа.

Как мы видим здесь, SG уже структурировал базовый макет заголовка, и если мы посмотрим в руководстве по API для этого конкретного класса базы данных, мы увидим, что большинство полей здесь существуют в этом классе, что позволяет нам просто использовать ‘code’, ‘cost’, ‘bulkUnit’ и т. д., как они определены здесь.

Обратите внимание: аналогично тому, как мы рассматривали выше структурирование наших файлов JSON, первичный ключ (code) должен быть включен.

Мы также можем перемещаться по классам базы данных аналогично тому, как мы видели выше при структурировании импорта JSON. Мы можем видеть это в нашем примере выше с помощью ‘units.code’, В пределах ‘Commodity’ класс, у нас есть ‘WeightUnits’ класс (определяемый как ‘units’).

По этой ссылке на ‘WeightUnit’ class покажет нам, что для определения кода единицы веса это ‘code’ в этом классе, поэтому, чтобы перейти к этому из нашего ‘Commodity’ отправной точкой будет ‘units.code’.

Здесь мы можем пройти столько уровней, сколько захотим, просто они должны быть связаны в руководстве по API.

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

Файлы заголовков должны быть созданы как файлы CSV с 1 значением в каждой ячейке верхней строки, пока мы не определим все данные, которые хотим импортировать или экспортировать. Затем этот файл csv необходимо сохранить, а затем отредактировать его расширение, чтобы оно стало ‘csvh’ файл (для этого необходимо включить просмотр расширений файлов в Windows).

Любые изменения в файле csvh следует вносить после его преобразования обратно в файл csv и редактирования в этом формате.

Заголовки, используемые для импорта, должны быть размещены в:

<installdir>\SG Control Center\gateway\import\column_defs

Заголовки, используемые для экспорта, должны быть размещены в:

<installdir>\SG Control Center\gateway\export\order

Теперь мы можем посмотреть, как мы будем выполнять импорт и экспорт.

6.2. Импорт

Как только наши соответствующие файлы заголовков будут на месте, нам нужно заполнить наш CSV-файл для импорта.

Как уже упоминалось, данные в нашем CSV-файле должны иметь ту же структуру, что и соответствующий заголовочный файл, т. е. правильные данные должны находиться в правильном столбце, чтобы импорт был успешным. Чтобы придерживаться нашего примера с товаром, мы можем видеть, что в этом примере ниже мы включили данные заголовка, чтобы помочь нам с вводом данных. Однако это не обязательно включать (см. «Игнорировать заголовки» ниже).

После того, как мы настроим это, мы можем продолжить заполнять csv, чтобы включить все товары, которые мы хотим импортировать.

После завершения csv можно выполнить импорт, перетащив соответствующим образом отформатированные и названные файлы csv в ‘\SG Control Center\gateway\import’. Соглашения об именах для этих файлов определены в рабочем листе сопоставления интеграции V5, поэтому для товаров мы можем видеть, что это:

Так, например, имя нашего файла может называться «commodity-0530231803.csv», чтобы сообщить нам, что он был импортирован 30 числа.^th май 2023 в 18:03. Нет установленного предпочтения порядка даты/времени, поэтому SG рекомендует использовать любой формат, который лучше всего подходит для каждого клиента (это может в конечном итоге определяться используемой внешней ERP).

После того, как мы поместим наши файлы в нужную папку, Центр управления автоматически обработает их, если в шлюзе разрешен импорт. Система предоставит диалог, чтобы сообщить нам, был ли процесс успешным или нет. Дополнительную информацию об этом вместе с журналами можно найти в разделе «Шлюз» Центра управления.

Файлы также можно импортировать вручную из других мест, щелкнув правой кнопкой мыши значок Центра управления в системной попытке и выбрав Шлюз > Импорт файла.

Затем это откроет диалог в центре управления, чтобы выбрать соответствующий файл CSV.

Затем в самом шлюзе мы можем настроить параметры процесса импорта:

Настройки здесь могут быть определены следующим образом:

Импорт включен – разрешает импорт, позволяя шлюзу сканировать папку импорта на наличие CSV-файлов по мере их перетаскивания туда.
Вставить дочерние сущности – позволяет шлюзу динамически создавать внутренние объекты, если они связаны в CSV-файле. Хорошим примером этого может быть импорт формулы, в которой перечислены товары, еще не присутствующие в базе данных. В этом случае Шлюз создаст для нас эти «дочерние» объекты при условии предоставления первичного ключа для товара (кода).
Игнорировать заголовки – заставляет шлюз пропускать первую строку (строку) импортированного CSV. Это полезно, если файл заголовка включен в файл импорта csv.
Уровень проверки – устанавливает способ проверки данных при их импорте шлюзом. Здесь есть 2 варианта:
- Предупреждать – Если в файле есть ошибка и строка не может быть импортирована, система сообщит вам об этом, но продолжит попытки обработать остальную часть файла.
- выкинуть - Если в файле существует ошибка, а строка не может быть импортирована, система прервет процесс и сообщит вам об ошибке.

Затем изменения в настройках можно применить в правом верхнем углу этой панели. Чтобы изменения вступили в силу, необходимо перезапустить Центр управления.

6.3. Экспорт

Экспорт через метод обмена файлами csv в значительной степени управляется заголовочным файлом и той информацией, которая запрашивается у системы. Если мы правильно структурируем их, используя руководство по API, то мы должны получить все данные, которые нам нужны, в правильном порядке.

В самом шлюзе мы также можем установить параметры против процесса экспорта:

Здесь мы можем использовать предоставленные флажки, чтобы выбрать, какие данные мы хотим экспортировать, в зависимости от точек данных, которые мы хотим видеть.

Обратите внимание, что начальные классы базы данных здесь, такие как ‘BatchConsumption’ и ‘SystemLogs’ отличаются от тех, с которых мы начали бы импорт, но если мы сможем успешно ориентироваться в руководстве по API для этих классов, мы сможем создать подходящий файл заголовка.

После того, как мы выбрали то, что хотим экспортировать, нужно просто ввести интервал экспорта (в миллисекундах) в левом верхнем углу и применить это значение (0 никогда не будет экспортироваться) в правом верхнем углу. Чтобы изменения вступили в силу, необходимо перезапустить Центр управления.

Экспортированные файлы csv будут помещены в ‘<installdir>\SG Control Center\gateway\export’ by default.

7. Частота и последовательность

Независимо от методологии, используемой для интеграции с V5 Traceability, частота и уровень автоматизации импорта и экспорта данных являются элементами процесса, которые можно настроить в соответствии с требованиями каждого клиента.

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

На этом этапе также может быть установлен определенный порядок импорта, поэтому, например, мы можем импортировать спецификацию перед заказом на работу, относящимся к этой спецификации. Мы могли бы сделать это, последовательно загружая файлы в каталог импорта или конечные точки API URI.

Как показано выше, мы также можем настроить шлюз для экспорта через определенные промежутки времени, чтобы отправлять данные обратно в систему ERP.

Импортом и экспортом можно управлять почти в режиме реального времени или выполнять через заданные промежутки времени. Используя маршрут API, можно легко управлять как импортом, так и экспортом почти в реальном времени. Частота импорта для метода совместного использования файлов csv зависит от конкретного внедряемого решения ERP/промежуточного программного обеспечения, а частота экспорта управляется через Центр управления, как описано выше.