API для построения отчетов
Классы
Класс ReportContext
Служит для получения данных для построения отчётов.
| Члены класса | Описание |
|---|---|
| public RPerson CurrentPerson { get; } | Получение пользователя, подключенного к системе. |
| public IList<RObject> Objects { get; set; } | Коллекция объектов для построения отчёта. Это свойство должно быть проинициализировано, если отчёт строится по объектам. |
| public RType GetType(int id); | Получение типа по идентификатору. |
| public RType GetType(string name); | Получение типа по имени. |
| public IList<RType> GetTypes(); | Получение всех типов, зарегистрированных в базе. |
| public ROrganisationUnit GetOrganisationUnit(int id); | Получение организационной единицы по идентификатору. |
| public IList<ROrganisationUnit> GetOrganisationUnits(); | Получение всех организационных единиц, зарегистрированных в системе. |
| public RPerson GetPersonOnPosition(int id); | Получение пользователя, состоящего на должности с указанным идентификатором. |
| RPerson GetPerson(int id); | Получение пользователя по идентификатору. |
| public IList<RPerson> GetPeople(); | Получение всех зарегистрированных в системе пользователей. |
| public RObject GetObject(Guid id); |
Получение объекта по идентификатору. Параметры: builder - конструктор поисковых запросов, contextId - идентификатор объекта, в контексте которого будет производиться поиск. При значении null поиск производится по всей базе. Подробнее см. Поисковые запросы. |
| public IList<RObject> GetObjects(IEnumerable<Guid> ids); | Пакетное получение объектов по идентификаторам. |
| public IList<RObject> GetObjects(IQueryBuilder builder, Guid? contextId = null); |
Получение объектов, соответствующих поисковому запросу. Параметры: builder - конструктор поисковых запросов. Подробнее см. в Поисковые запросы. |
| public IList<INUserState> GetUserStates(); | Возвращает список пользовательских состояний, зарегистрированных в базе данных. |
| public Stream OpenFile(INFile file); | Открытие файла на чтение. При отсутствии файла в локальном кеше содержимое файла будет скачано с сервера. |
| public IList<RChatMessage> LoadMessages((Guid chatId, DateTime dateFromUtc, DateTime dateToUtc, int maxNumber); |
Получение сообщений по чату. Параметры: chatId - идентификатор чата, dateFromUtc - минимальное время создания сообщения, dateToUtc - максимальное время создания сообщения, maxNumber - максимальное количество возвращаемых сообщений. Перед вызовом этого метода для нового чата неоходимо вызвать метод LoadChat для текущего чата. |
| public RChatInfo LoadChat(Guid chat); | Получение чата с указанным идентификатором. |
| string GetPilotUrl(Guid targetObjectId, DateTime? versionUtc = null); | Конструктор строки для формирования ссылки на объекты Pilot |
Пример инициализации для получения объектов типа с именем document:
C#:
ReportContext context = new ReportContext();
private void PilotReport_DataSourceDemanded(object sender, System.EventArgs e)
{
LongRunning.Start(this, () => {
var documentType = context.GetType("document");
var objectsBuilder = QueryBuilder.CreateObjectQueryBuilder();
objectsBuilder.Must(ObjectFields.TypeId.Be(documentType.Id));
var objects = context.GetObjects(objectsBuilder);
DataSource = context;
});
}
Класс RObject
Представляет собой объект.
| Члены класса | Описание |
|---|---|
| public Guid Id { get; } | Идентификатор объекта. |
| public RType Type { get; } | Тип объекта. |
| public RObject Parent { get; } | Родительский объект. |
| public RPerson Creator { get; } | Создатель объекта. |
| public DateTime CreatedUtc { get; } | Дата создания объекта в формате UTC. |
| public string Title { get; } | Отображаемое имя объекта. |
| public IDictionary<string, object> Attributes { get; } | Словарь атрибутов объекта, в котором ключ — имя атрибута. |
| public IList<INFile> Files { get; } | Список текущих файлов. |
| public IList<INFilesSnapshot> FilesSnapshots { get; } | Список предыдущих версий файлов. |
| public IDictionary<int, Access> Access { get; } | Словарь прав доступа к объекту, в котором ключ — идентификатор организационной единицы, а значение — уровень доступа. |
| public bool IsSecret { get; } | Определяет, является ли объект скрытым. |
| public bool IsDeleted { get; } | Определяет, является ли объект безвозвратно удаленным |
| public bool IsInRecycleBin { get; } | Определяет, является ли объект удаленным в корзину. |
| public IList<RObject> Children { get; } | Коллекция дочерних объектов. |
| public IList<RObject> SourceFiles { get; } | Коллекция объектов, с которыми установлена связь типа Исходный файл. |
| public IList<RPerson> Subscribers { get; } | Список подписчиков на объект. |
| public IList< RRelation> Relations { get; } | Горизонтальные связи объекта. |
Класс RChatMessage
Представляет собой сообщение.
| Члены класса | Описание |
|---|---|
| public Guid Id { get; } | Идентификатор сообщения. |
| public Guid CreatorId { get; } | Идентификатор пользователя, создавшего сообщение. |
| public RPerson Creator { get; } | Пользователь, создавший сообщение. |
| public int Type { get; } |
Тип сообщения.
Возможные значения: RMessageType.TextMessage = 0 - Текстовое сообщение, RMessageType.ChatCreation = 1 - Сообщение создания чата, RMessageType.ChatMembers = 2 - Сообщение редактирования участников чата: добавление/удаление/редактирование, RMessageType.MessageRead = 3 - Сообщение о прочтении другого сообщения, RMessageType.MessageAnswer = 4 - Сообщение-ответ на другое сообщение, RMessageType.ChatChanged = 5 - Сообщение редактирования чата, RMessageType.ChatRelation = 6 - Сообщение о добавлении связи, RMessageType.MessageDropUnreadCounter = 7 - Сообщение о сбросе счетчика непрочитанных сообщений, RMessageType.EditTextMessage = 8 - Отредактированное текстовое сообщение (свойство Text такого типа сообщения содержит отредактированный текст) |
| public DateTime Date { get; } | Дата создания сообщения на сервере. |
| public string Text { get; } | Текст сообщения. Заполнен только для сообщения с типом 0 и 8. |
| public IEnumerable<RChatMessage> RelatedMessages { get; } | Коллекция связанных сообщений. |
Класс RChatInfo
Представляет собой чат.
| Члены класса | Описание |
|---|---|
| public Guid Id { get; } | Идентификатор чата. |
| public string Name { get; } | Наименование чата. |
| public string Description { get; } | Описание чата. |
| public Guid CreatorId { get; } | Идентификатор пользователя, создавшего чат. |
| public RPerson Creator { get; } | Пользователь, создавший чат. |
| public int Type { get; } | Тип чата. |
| public Guid? LastMessageId { get; } | Идентификатор последнего сообщения в чате. |
| public DateTime CreationDateUtc { get; } | Дата создания чата. |
Класс RType
Представляет собой тип объекта.
| Члены класса | Описание |
|---|---|
| public int Id { get; } | Идентификатор типа. |
| public string Name { get; } | Имя типа. |
| public string Title { get; } | Отображаемое имя типа. |
| public byte[] Icon { get; } | Иконка типа в формате SVG. |
| public int Sort { get; } | Содержит порядковый номер сортировки. |
| public bool HasFiles { get; } | Определяет, может ли объект этого типа содержать файлы. |
| public bool IsDeleted { get; } | Определяет, был ли удален тип. |
| public TypeKind Kind { get; } | Определяет, является ли тип пользовательским или системным. |
| public bool IsMountable { get; } | Определяет, может ли объект этого типа быть смонтирован на диск. |
| public bool IsService { get; } | Определяет, является ли тип сервисным (скрытым от отображения). |
| public IList<NAttribute> Attributes { get; } | Возвращает список атрибутов типа. |
| public IList<RType> Children { get; } | Возвращает коллекцию дочерних типов. |
Класс NAttribute
Представляет собой атрибут типа.
| Члены класса | Описание |
|---|---|
| public string Name { get; } | Имя типа. |
| public string Title { get; } | Отображаемое имя типа. |
| public bool Obligatory { get; } | Определяет, является ли атрибут обязательным к заполнению. |
| public int DisplaySortOrder { get; } | Содержит порядковый номер сортировки атрибута при отображении. |
| public bool ShowInTree { get; } | Определяет, будут ли отображаться атрибут в карточке объекта. |
| public bool IsService { get; } | Определяет, является ли атрибут сервисным. |
| public string Configuration { get; } | Дополнительные параметры атрибута. |
| public MAttrType Type { get; } |
Тип атрибута. Возможные значения: Integer, Double, DateTime, String. |
| public int DisplayHeight { get; } | Количество строк, зарезервированных для отображения атрибута строкового типа. |
Класс RRelation
Представляет собой горизонтальную связь между объектами.
| Члены класса | Описание |
|---|---|
| public Guid Id { get; } | Уникальный идентификатор связи. |
| public RelationType Type { get; } |
Получение типа связи:
|
| public RRelation Target { get; } | Получение связанного объекта. |
| public string Name { get; } | Наименование связи. |
Класс RPerson
Представляет собой пользователя.
| Члены класса | Описание |
|---|---|
| public int Id { get; } | Идентификатор пользователя. |
| public string Login { get; } | Логин пользователя. |
| public string DisplayName { get; } | Отображаемое имя пользователя. |
| public string Comment { get; } | Комментарий к пользователю. |
| public string Sid { get; } | Идентификатор пользователя из Active Directory. |
| public bool IsDeleted { get; } | Определяет, был ли удален пользователь. |
| public bool IsAdmin { get; } | Определяет, является ли пользователь администратором. |
| public ROrganisationUnit MainPosition { get; } | Основная должность пользователя. |
| public IList<ROrganisationUnit> Positions { get; } | Список всех должностей, на которых состоит пользователь. |
Класс ROrganisationUnit
Представляет собой организационную единицу (должность или подразделение).
| Члены класса | Описание |
|---|---|
| public int Id { get; } | Идентификатор организационной единицы. |
| public string Title { get; } | Отображаемое имя организационной единицы. |
| public bool IsPosition { get; } | Определяет, является ли организационная единица должностью. Значение false означает, что организационная единица является подразделением. |
| public bool IsDeleted { get; } | Определяет, была ли удалена организационная единица. |
| public RPerson Person { get; } | Возвращает пользователя, состоящего на должности. |
| public IList<ROrganisationUnit> Children { get; } | Список дочерних организационных единиц подразделения. |
Класс LongRunning
Выполнение скриптов отчёта происходит в UI потоке, поэтому выполнение длительных операций (поисковые запросы, работа с файлами и т.д.) может приводить к неотзывчивости пользовательского интерфейса во время построения отчёта. Для обеспечения отзывчивости интерфейса длительные операции необходимо запускать с помощью статического метода LongRunning.Start(ScriptingReport, Action).
Пример:
LongRunning.Start(this, () => {
var currentPerson = context.CurrentPerson;
var builder = QueryBuilder.CreateEmptyQueryBuilder();
builder.Must(AttributeFields.DateTime("dateOfAssignment"). BeInRange(DateTime.UtcNow.AddDays(-14), DateTime.UtcNow));
builder.Must(AttributeFields.OrgUnit("executor").Be(currentPerson.Id));
builder.MustNot(AttributeFields.State("state").Be(SystemStates. NEXTTASK_REVOKED_STATE_GUID));
context.Objects = context.GetObjects(builder);
DataSource = context;
});
Поисковые запросы
Основой для составления поискового запроса является fluent интерфейс IQueryBuilder, который представляет собой конструктор запросов на основе различных условий.
При добавлении нескольких условий попадание в результаты поиска осуществляется только при одновременном выполнении всех условий.
Члены IQueryBuilder
| Члены класса | Описание |
|---|---|
| IQueryBuilder Must(ISearchTerm term) | Определяет условие, значение которого должно соответствовать истине для попадания в результаты поиска. |
| IQueryBuilder MustAnyOf(params ISearchTerm[] terms) | Определяет набор условий, при выполнении хотя бы одного из которых происходит попадание в результаты поиска. |
| IQueryBuilder MustNot(ISearchTerm term) | Определяет условие, значение которого должно соответствовать "ложь" для попадания в результаты поиска. |
Статические методы для создания экземпляра IQueryBuilder
| Метод | Описание |
|---|---|
| QueryBuilder.CreateObjectQueryBuilder() | Создает конструктор поискового запроса для объектов. Содержит в себе предустановленные условия для попадания в поисковую выдачу только неудалённых объектов пользовательских типов. |
| QueryBuilder.CreateEmptyQueryBuilder() | Создает пустой конструктор поискового запроса. Может быть использован для сложных сценариев поиска. |
Конструирование условия поиска для объектов
| Основа | Конструкция | |
|---|---|---|
| Идентификатор объекта. |
var builder = QueryBuilder.CreateObjectQueryBuilder(); builder.Must(ObjectFields.Id.Be(objId)); |
|
| Идентификатор родительского объекта. |
var builder = QueryBuilder.CreateObjectQueryBuilder(); builder.Must(ObjectFields.ParentId.Be (parentId)); |
|
| Идентификатор типа объекта. |
var type = context.GetType("document"); var builder = QueryBuilder.CreateObjectQueryBuilder(); builder.Must(ObjectFields.TypeId.Be(type.Id)); |
|
| Пользователь-создатель объекта. |
var builder = QueryBuilder.CreateObjectQueryBuilder(); builder.Must(ObjectFields.CreatorId.Be (context.CurrentPerson.Id)); |
|
| Дата создания объекта. |
var to = DateTime.UtcNow; var from = to.AddDays(-5); var builder = QueryBuilder.CreateObjectQueryBuilder(); builder.Must(ObjectFields.CreatedDate.BeInRange (from, to)); |
|
| Признак, является ли объект скрытым. |
var builder = QueryBuilder.CreateObjectQueryBuilder(); builder.Must(ObjectFields.IsSecret.Be (true)); |
|
| Признак, что любой атрибут содержит текстовое значение. |
var builder = QueryBuilder.CreateObjectQueryBuilder(); builder.Must(ObjectFields.AllText.Be ("конструк*")); |
|
| Значение конкретного атрибута: | Строкового |
var builder = QueryBuilder.CreateObjectQueryBuilder(); builder.Must(AttributeFields.String("Name") .Be("конструк*")); |
| Целочисленного |
var builder = QueryBuilder.CreateObjectQueryBuilder(); builder.Must(AttributeFields.Integer("Code") .Be(5)); |
|
| С плавающей запятой |
var builder = QueryBuilder.CreateObjectQueryBuilder(); builder.Must(AttributeFields.Double("Price") .BeInRange(3.5, 8.9)); |
|
| Даты |
var to = DateTime.UtcNow; var from = to.AddDays(-5); var builder = QueryBuilder .CreateObjectQueryBuilder(); builder.Must(AttributeFields.DateTime("Hired").BeInRange(from, to)); |
|
Отладка скриптов отчёта
Для включения отладки скриптов необходимо отредактировать конфигурационный файл Pilot-ICE Enterprise. Данный файл может быть найден по пути: %PROGRAMFILES%\ASCON\Pilot-ICE Enterprise\Ascon.Pilot.PilotEnterprise.exe.config. В файле необходимо раскомментировать секцию:
<system.diagnostics>
<switches>
<add name="AllowDebugXtraReportScripts" value="BreakWhenDebuggerAttached"/>
</switches>
</system.diagnostics>
Для отладки скриптов требуется Microsoft Visual Studio 2017 и старше.
Для начала отладки скриптов необходимо присоединиться к процессу Pilot-ICE Enterprise. Для этого в Visual Studio нажмите Отладка (Debug) → Присоединиться к процессу... (Attach to Process...) и в появившемся диалоге выберите процесс Ascon.Pilot.PilotEnterprise. После успешного присоединения к процессу вызовите команду построения отчёта в Pilot-ICE Enterprise. В Visual Studio автоматически сработает точка останова на конструкторе скрипта отчёта.