Общие сведения

Вместе с платформой разработчик получает два уровня API:

Базовый API — универсальное средство программного доступа ко всем функциям платформы Docsvision. Может быть использован в проектах, основанных на .NET (сборка DocsVision.Platform.ObjectManager.dll) и COM (сборка ObjectManager.dll) технологиях.
Высокоуровневый слой, объектная модель Docsvision (далее — "объектная модель") — набор базовых объектов и функциональных возможностей, с помощью которых могут быть реализованы специализированные модели сущностей выбранной предметной области.

Использование готовых базовых типов позволяет снизить издержки на разработку собственного решения, обеспечит прозрачность архитектуры, простоту расширения и интеграции нескольких решений, включая Базовые объекты (являются частью платформы Docsvision). API данного уровня является удобным средством для работы с карточками. Сборки данного уровня API имеют только .NET-версию.

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

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

Это, например, с некоторыми ограничениями, доступ к данным карточек.
Задачи, которые эффективнее решать с использованием методов объектной модели.

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

Например: поиск данных по секции карточки.
Задачи, которые не могут быть решены с помощью API Docsvision.

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

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

Далее приведена информация относительно некоторых ключевых объектов и терминов API Docsvision, которые необходимы для понимания последующих примеров разработки.

Пользовательская сессия и контекст объектов

В API Docsvision существуют две ключевые сущности, представляющие функциональные возможности своего слоя API: пользовательская сессия (или сессия пользователя) и контекст объектов.

Пользовательская сессия: Пользовательская сессия является главным объектом в базовом API и обеспечивает единую точку доступа к остальным функциям данного API.

С физической точки зрения, сессия — контекст сеанса связи с сервером для конкретного пользователя. Сессия ассоциируется с доменной учетной записью, от имени которой установлено соединение, и в дальнейшем все привилегии на доступ к данным из этой сессии проверяются относительно этой учетной записи.

В рамках сессии кэшируются все данные, к которым производилось обращение, для ускорения последующего доступа к ним. Размер кэша и продолжительность пребывания в нём данных автоматически регулируются платформой, на основании внутренних алгоритмов. Разработчик может только явно потребовать удаления конкретных объектов из кэша (при помощи методов этих объектов).

Создание сессии является первоочередной задачей при разработке любых внешних (относительно платформы) приложений, работающих с Docsvision. При разработке внутрисистемных объектов, таких как скрипты карточек (в Конструкторе скриптов или Конструкторе разметок) или бизнес-процессы, готовая сессия передается при инициализации.
Контекст объектов: Контекст объектов — элемент объектной модели, который обеспечивает загрузку и сохранение данных карточек. Контекст объектов также предоставляет доступ к функциям, реализующим основную бизнес-логику для работы с бизнес-объектами. Функциональные возможности контекста объектов обеспечивают инициализацию объектной модели карточки при загрузке её данных из базы данных, а также последующее связывание данных.

Контекст объектов должен быть проинициализирован, чтобы работать с объектной моделью карточки. Исключением являются разработка скриптов карточек и бизнес-процессов — в этих случаях готовый контекст объектов будет доступен из базового класса (для скрипта карточки) и из параметров вызванного метода (для бизнес-процесса).

Для инициализации контекста объектов потребуется пользовательская сессия.

Менеджеры базового API

Менеджеры — сущности базового API, в которых собраны методы для работы с различными объектами платформы.

Например, есть менеджеры для работы с карточками, файлами, безопасностью и прочие:

AccessManager — менеджер объектов безопасности, в котором представлены методы управления правами доступа на объекты системы, а также методы для работы с крипто-объектами.
CardManager — менеджер карточек. Данный менеджер предоставляет полный набор средств для работы с экземплярами карточек: создание, получение и удаление.
ExtensionManager — менеджер расширений. Данный менеджер предоставляет единственный метод GetExtensionMethod, возвращающий метод серверного расширения.
FileManager — менеджер файлов, предоставляющий методы для работы с файлами: создание, получение и удаление, а также некоторые другие.
LicenseManager — менеджер лицензий. Данный менеджер предоставляет два метода для учета числа подключений в лицензии дополнительного модуля.
LockManager — менеджер блокировок. Предоставляет методы получения объектов блокировки с объекта системы. Для полнофункциональной работы могут потребоваться права администратора.
LogManager — менеджер журнала. Данный менеджер содержит операции для работы с системным журналом.
ReportManager — менеджер хранимых процедур. Предоставляет метод для получения данных хранимой процедуры.

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

CardManager cardManager = userSession.CardManager;

Сервисы объектной модели

На уровне объектной модели Docsvision принято выносить бизнес-логику из объектной модели карточки в отдельные сервисы, доступ к которым можно получить непосредственно из контекста объектов. Сервисы выполняют задачи, аналогичные тем, что выполняют менеджеры базового API, но со специализацией на конкретных типах карточек — есть сервисы для работы с документами, с заданиями, со справочниками и т.п.

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

В базовой поставке Docsvision предоставляются системные сервисы (для работы с блокировками, доступом и т.п.), а также сервисы для работы с карточками библиотеки карточек Базовые объекты. Полный список сервисов приведён далее.

Таблица 1. Полный список сервисов
Область действия	Сервис	Назначение
Общего назначения	`IAccessCheckingService`	Определяет функции получения списка ролей и доступных операций сотрудника в пределах заданной карточки. Предоставляет методы сброса кэша ролевой модели.
	`IBaseCardService`	Предоставляет методы установки и проверки ЭП, генерации дайджеста и управления бизнес-процессом.
	`ILockService`	Позволяет управлять состоянием блокировки объектов, получать информацию о текущем состоянии и владельце блокировки.
	`ILogService`	Определяет методы добавления и получения записей журнала карточки.
	`IServerExtensionProxyService`	Позволяет выполнять методы серверного расширения BackOffice.
	`ISettingsCardService`	Предоставляет методы доступа к системным настройкам.
	`ICryptService`	Сервис шифрования файлов карточек приложения Базовые объекты
Карточки	`IDocumentService`	Предназначен для работы с карточками типа Документ
	`IBarcodeService`	Определяет методы генерации и печати штрих-кодов карточки документа.
	`ITaskService`	Предназначен для работы с карточками типа Задание
	`ITaskGroupService`	Предназначен для работы с карточками типа Группа заданий
	`ITaskListService`	Предназначен для работы с карточками типа Список ссылок на карточки заданий
	`ICategoryListService`	Предназначен для работы с карточками типа Список категорий
	`INumeratorCardService`	Предназначен для работы с карточками типа Карточка нумератора
	`INumerationRulesService`	Предназначен для работы с карточками типа Конструктор правил нумерации
	`IReferenceListService`	Предназначен для работы с карточками типа Список ссылок на карточки
	`ICalendarService`	Предназначен для работы с карточками типа Бизнес-календарь
	`IVersionedFileCardService`	Предназначен для работы с карточками типа Карточка файла с версиями
	`ISurveyService`	Предназначен для работы с карточками типа Список опросов
	`IUserProfileCardService`	Предназначен для работы с карточками типа Карточка настроек пользователя
Конструкторы	`IRoleModelService`	Конструктор ролей
	`IBaseUniversalService`	Карточка строки справочника
	`ILayoutService`	Конструктор разметок
	`IScriptingService`	Конструктор скриптов
	`IStateService`	Конструктор состояний
Справочники	`ICategoriesService`	Справочник категорий
	`IKindService`	Справочник видов карточек
	`ISettingsService`	Предоставляет методы для работы с настройками расширений справочника видов.
	`IStaffService`	Справочник сотрудников
	`IPartnersService`	Справочник контрагентов
	`IServersService`	Справочник серверов
	`ISignatureLabelService`	Справочник меток подписей
	`ILinkService`	Справочник ссылок

Чтобы получить один из сервисов, необходимо использовать метод GetService контекста объектов, уточнив тип (публичный интерфейс) запрашиваемого сервиса:

IDocumentService documentService = objectContext.GetService<IDocumentService>(); (1) (2)

1	`objectContext` — сущность контекста объектов.
2	`IDocumentService` — интерфейс, реализуемый сервисом.

Преобразователи данных

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

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

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

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

Объекты хранения данных

Ключевым объектом Docsvision, соответствующим сущностям целевой системы, является карточка. С карточками работают как пользователи, так и разработчики. Если для пользователя карточка — это прежде всего графический интерфейс, на который определённым образом выведены данные, то для разработчика — это объектная модель, метаданные и сами данные.

Прежде чем перейти к дальнейшему описанию необходимо дать определения нескольким ключевым понятиям:

Тип карточки — описание сущности целевой системы в Docsvision.

Если проводить аналогию с программированием, то тип карточки — это класс.

В Docsvision представлено большое количество типов карточек. Если существующие типы недостаточно точно отражают объект целевой системы, может быть разработан собственный с уникальной бизнес-логикой.

Экземпляр карточки — экземпляр карточки определённого типа. Экземпляр карточки обладает уникальным идентификатором, по которому карточка может быть получена из базы данных. Если следовать аналогии, то экземпляр карточки — это объект.
Поле — элемент структуры карточки, предназначенный для непосредственного хранения данных определённого типа. Также может ссылаться на другие элементы данной или другой карточки.
Секция — элемент структуры карточки, объединяющий группу полей.

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

На уровне базы данных секция — это таблица, а поле — это столбец данной таблицы.

Конкретный набор секций и полей, а также их характеристики определяет схема карточки. Каждый тип карточек обладает собственной схемой, что позволяет реализовать в системе объекты, приближенные по характеристикам к сущностям выбранной предметной области. К примеру, для хранения информации о книгах библиотеки, может быть реализована карточка типа Книга с полями: название, автор, дата издания и т.п. Для хранения информации о входящих документах компании можно реализовать карточку типа Входящий документ с полями: отправитель, дата отправки, специалист, который должен получить данный документ.

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

Это может быть востребовано, к примеру, если в карточке типа Книга должны храниться сведения о нескольких авторах этой книги. Помимо табличного варианта организации строк секции, предусмотрена иерархическая структура, при которой строка секции может содержать подчиненные строки из этой же секции. Такая структура секции обычно используется в справочниках — карточки, представленные в единственном экземпляре (ограничение устанавливается схемой карточки), данные из которых используются в других карточках. Примером справочника может служить Справочник сотрудников из библиотеки карточек Базовые объекты, данные которого используются во многих других типах карточек данной библиотеки.

Структура секции определяются её типом:

Плоская секция — может содержать только одну строку. Создание второй строки будет воспринято как ошибка.
Коллекционная секция — может содержать набор строк. Секция данного типа по сути аналогична обычной таблице.
Иерархическая секция — может содержать иерархию строк, в которой строка может иметь в подчинении строки этой же секции.

На уровне базы данных секция строка секции — это строка таблицы, а секция — сама таблица.

Далее, для обобщения изложенной выше информации, представлена структура экземпляра карточки некого типа. Подобную структуру можно составить на основе данных, предоставляемых программой "Docsvision Explorer" из комплекта "Resource Kit".

Рисунок 1. Структура экземпляра карточки

Приведенную карточку (в сочетании со схемой типа карточки) можно охарактеризовать следующим образом:

Карточка содержит две секции: Секция "A" (иерархическая) и Секция "B" (плоская).
Секция "A" содержит две строки: Строка 1 и Строка 2. У Строки 1 есть подчиненная строка — Подстрока 1. В секции определено два поля: Поле 1 и Поле 2.
Секция "B" содержит единственную строку (Строка 1), что определено ограничениями плоской секции. В секции определены поля: Поле 1, Поле 2 и Поле 3.
Секция "B" также имеет подчиненную секцию — Подсекция "С" (коллекционная), которая содержит две строки: Строка 1 и Строка 2. В секции определено единственное поле — Поле 1.

Для представления данных карточки в API Docsvision реализовано несколько классов, специфичных для выбранного уровня (слоя) API. Далее приведены такие типы для обоих уровней API Docsvision.

Объекты хранения данных на уровне базового API

Типы, приведенные далее, определены в сборке DocsVision.Platform.ObjectManager.dll.

CardData — данные экземпляра карточки. Включает совокупность всех данных секций и атрибутов конкретного экземпляра карточки.
SectionData — данные секции карточки, из которой может быть получена коллекция всех её строк.

RowDataCollection — коллекция строк секции, из которой могут быть выбраны конкретные строки.

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

RowData — строка секции. Выбрать строку из коллекции строк можно по уникальному идентификатору, по номеру в коллекции либо перебором.
SubSectionData — подмножество строк (подсекция) секции, подчинённых определённой строке из родительской секции.
Field — поле строки секции, а точнее его значение.

Обычный сценарий доступа к данным карточки с привлечением приведенных типов следующий:

Получить экземпляр карточки — CardData.
Получить нужную секцию из карточки: CardData.Sections[Section_ID].
Получить коллекцию строк выбранной секции: SectionData.Rows.
Выбрать конкретную строку из секции: SectionData.Rows[Row_ID].
Получить значение поля по псевдониму: RowData[FieldAlias].

Объекты хранения данных на уровне объектной модели

Типы, приведенные далее, определены в сборках: DocsVision.BackOffice.ObjectModel.dll — содержит типы, описывающие сущности карточки и DocsVision.Platform.ObjectModel.dll — содержит общие базовые классы.

Приведенные далее сведения относятся только к карточкам, объектная модель которых унаследована от базового класса BaseCard. Если объектная модель создана на основе базовых классов из сборки DocsVision.Platform.ObjectModel.dll, механизм доступа к данным будет отличаться.

Объектная модель карточки предлагает гораздо меньшее (в сравнении с базовым API) число типов:

BaseCard — базовый класс карточки, который содержит коллекции всех строк её секций.
BaseCardSectionRow — строка секции, предоставляющая доступ к своим полям.

Как видно из списка, в объектной модели нет отдельных классов для секций и полей, что упрощает сценарий доступа к данным, который в общем случае будет следующий:

Получить экземпляр карточки — тип BaseCard, либо унаследованный от него.
Выбрать строки конкретной секции, воспользовавшись методом BaseCard.GetSection.
Выбрать строку из полученной коллекции.
Получить значение нужного поля по его псевдониму: BaseCardSectionRow["FieldAlias"].

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

Получить экземпляр карточки, к примеру, типа SampleCard — унаследован от типа BaseCard.
Получить коллекцию строк секции, из соответствующего публичного свойства класса: SampleCard.SampleSection.
Выбрать нужную строку секции: SampleCard.SampleSection[0]. Если секция является плоской и это учтено при реализации объектной модели, то данный шаг пропускается.
Получить значение поля: SampleCard.SampleSection[0].SampleField.

Помимо типов, приведенных выше и относящихся к доступу к данным карточки, в процессе разработки типов могут быть задействованы дополнительные типы, к примеру, относящиеся к справочникам. Если такие типы будут использованы далее, будет приведено их описание. Также описание большинства типов API Docsvision приведено в разделе Библиотека классов.