Основой модуля являются макросы, используемые повсеместно для выгрузки и загрузки данных в Систему. Макрос – это словесное описание обозначения имени атрибута или ссылки на существующий объект. Макросы показывают программе, в какой атрибут заносить загружаемые данные и из какого атрибута извлекать данные. В модуле существует поддержка пяти типов макросов - для атрибута типа, для атрибута связанного справочника, запрограммированные макросы для загрузки файлов, макрос для атрибута родительского типа и атрибута типа связь.
На данный момент для импорта не поддерживаются макросы для атрибутов типа Организационная единица. Макросы для этих типов атрибутов будут проигнорированы.
¶ Макрос: Атрибут типа
Используется для загрузки/выгрузки значений в/из определенный атрибут объекта указанного типа. Формат макроса имеет вид, описанный ниже. Для написания макроса необходимо знать системное имя объекта и системные имена его атрибутов.
Формат макроса имеет вид:
$<type name>.<attribute name><!>
- type name - внутреннее название типа объекта в БД;
- attribute name - название атрибута этого типа;
- ! – указывает, что данный макрос является первичным ключом.
Примеры: $lmp_contract.code; $lmp_contract.code!
Внутренние названия типов и атрибутов вы можете узнать, используя утилиту myAdmin, или же обратившись к Администратору системы.
Рис. 34. Тип объекта и его атрибуты в Pilot myAdmin
У каждого объекта есть зарезервированные (стандартные) атрибуты, которые можно использовать при составлении макроса. Например, такие атрибуты как:
- id - уникальный идентификатор объекта (доступен для экспорта и импорта в качестве первичного ключа);
- parent_id - уникальный идентификатор родительского объекта (данный идентификатор можно получить посредством контекстного меню, пункт Копировать идентификатор);
- created - дата создания и время (доступен только для экспорта);
- creator - создатель (ФИО) (доступен только для экспорта);
- display - отображаемое значение для объекта в системе (доступен для экспорта и импорта в качестве первичного ключа).
Эти данные об объекте скрыты и некоторые из них нигде не отображаются, но их можно узнать. Например, чтобы узнать id, нужно нажать ПКМ на объект и выбрать в контекстном меню «Копировать идентификатор».
Формат макроса с зарезервированным атрибутом имеет вид:
$<type name>.<RESERVED><!>
- RESERVED – это зарезервированный атрибут.
Примеры: $lmp_contract.id; $lmp_contract.id!
Например, шаблон для загрузки данных в справочник «Строительная документация», в котором написаны только макросы атрибута типа:
Рис. 35. Пример шаблона справочника
Обязательным условием при создании шаблона является указание особого макроса. Такой макрос является первичным ключом, и значения для этого макроса должны быть уникальны. Особый макрос обозначатся знаком восклицания ! в конце.
Особый макрос прописывается только к одному атрибуту в файле шаблона Справочника. В данном примере это макрос для атрибута Код.
В карточке такого атрибута (в утилите Pilot MyAdmin) для поля «Уникальность» рекомендуется выбирать значение «Запрещать создание дубликатов».
Первичный ключ – это значение, которое является уникальным в системе и используется в качестве уникального идентификатора объекта. Когда в системе создаётся объект (документ, CRS и т.д.) один или несколько его атрибутов будут являться первичными ключами. Атрибут, который будет использоваться в качестве первичного ключа, назначается в утилите Pilot myAdmin. Также все объекты имеют стандартный (зарезервированный) атрибут id, который всегда является первичным ключом объекта. В xlsx-файлах шаблонов загрузки документов, справочников и в xlsx-файлах шаблонов формирования CRS и TRM обязательно должен быть атрибут объекта, который будет являться первичным ключом для этого объекта. Макрос такого атрибута обозначается «!» и называется «Особый макрос». Особый макрос в таблице назначается только одному атрибуту объекта. По значениям колонки с особым макросом в системе происходит поиск этого объекта. В случае если в системе нет объекта со значением атрибута из колонки особого макроса – объект будет создан; если в системе уже есть объект с таким значением – атрибуты этого объекта будут обновлены.
Данные из колонок, для которых не прописан макрос, не попадают в Систему. Таким образом возможно ограничить попадающую в Систему информацию, добавляя макросы только к тем колонкам, данные из которых необходимо перенести в Pilot.
Для импорта атрибута типа «Состояние» при заполнении таблицы xlsx-файла необходимо использовать системное имя состояния. В ином случае будет выдана ошибка.
¶ Работа макроса, в случае если атрибут имеет тип нумератор
Если атрибут типа нумератор указан как первичный ключ, то:
- если значение для атрибута, указанного макросом отсутствует, то создаем новый объект;
- если значение для атрибута, указанного макросом, присутствует и объект с таким значением найден, то обновляем найденный объект;
- если значение для атрибута, указанного макросом, присутствует и объект с таким значением не найден, то создаем новый объект с заданным значением.
Если атрибут типа нумератор не указан как первичный ключ, то:
- если значение для атрибута, указанного макросом отсутствует, то заполняем атрибут автоматически;
- если значение для атрибута, указанного макросом, присутствует, то используем для атрибута заданное значение.
Данное поведение доступно для загрузки справочника, загрузки структуры и пакетной загрузки документации
¶ Макрос: Атрибут связанного справочника
Используется для загрузки данных в атрибут, представляющий собой ссылку на элемент справочника. Такие атрибуты имеют тип Element Book.
Макрос имеет формат:
$<type name>.<attribute name>.<linked attribute name>
- type name - название типа;
- attribute name - название атрибута (в данном случае атрибут обязательно должен быть типа Element book);
- linked attribute name - название атрибута связанного элемента справочника.
Например, нужно добавить новые договоры в справочник «Договоры». Карточка договора содержит возможность выбора «Контрагента» (системное имя атрибута ref_contractor) из связанного справочника "Контрагенты".
Рис. 36. Карточка и атрибутивный состав Элемента справочника
Для загрузки договора (системное имя типа lmp_contract) с контрагентом АО "ВНИИГ им. Б.Е. Веденеева", который является связанным элементом справочника «Контрагенты», нужен атрибут этого элемента. Например, этим атрибутом будет «Наименование» (системное имя атрибута name).
Рис. 37. Пример карточки элемента справочника в обозревателе проектов и системного имени атрибута элемента справочника
Макрос загрузки данных в атрибут «Контрагент»: $lmp_contract.ref_contractor.name.
Макросы для связанных справочников также поддерживают работу с зарезервированными атрибутами, как это описано в разделе выше.
Формат макроса с зарезервированным атрибутом имеет вид:
$<type name>.<attribute name>.<RESERVED>
- RESERVED – это зарезервированный атрибут.
Например: $lmp_contract.contractor.id
¶ Макрос: Родитель
Используется для выгрузки данных из системы. Позволяет получить значение атрибута родительского объекта. По строению макрос аналогичен предыдущим типам макросов и имеет вид:
$<type name>.parent.<attribute name>
или
$<type name>.parent.<RESERVED>
- type name - название типа;
- parent – означает что будет браться значение атрибута родителя (указывается далее);
- attribute name - название атрибута родителя;
- RESERVED - это зарезервированный атрибут.
Например, макрос атрибута name комплекта в котором находится TRM, будет иметь вид: $lmp_document_trm.parent.name, так как комплект является родительским объектом для находящегося в нём TRM.
Например, макрос для получения создателя комплекта в котором находится TRM, будет иметь вид: $lmp_document_trm.parent.creator, так как комплект является родительским объектом для находящегося в нём TRM, а атрибут creator зарезервированным атрибутом для получения создателя.
Если атрибут имеет тип Element Book, то макрос имеет следующий вид:
$<type name>.parent.<attribute name>.<linked attribute name>
или
$<type name>.parent.<attribute name>.<RESERVED>
- type name - название типа;
- parent – означает что будет браться значение атрибута родителя (указывается далее);
- attribute name - название атрибута родителя (в данном случае атрибут обязательно должен быть типа Element book);
- linked attribute name - название атрибута связанного элемента справочника;
- RESERVED - это зарезервированный атрибут.
Данный атрибут поддерживает комбинацию с самим собой и с макросом “Cвязь”. При комбинации данного макроса с самим собой и с макросом “Cвязь” часть, отвечающая за указание атрибута, отбрасывается, только у первого комбинируемого макроса. Например, макросы $type_name.parent.link… и $type_name.link.type_name.link… корректные, а макросы $type_name.parent.attribute.link… и $type_name.link.type_name.attribute_name.link… - нет.
Например, мы хотим получить наименование проекта (предположим что в качестве проекта выступает тип project, а в качестве наименования выступает аттрибут name) к которому относится документ (предположим что в качестве документа выступает тип documnent), зная что между документом и проектом есть еще объект комплект (предположим что в качестве комплекта выступает тип main_set), макрос будет иметь вид: $document.parent.parent.name.
¶ Макрос: Связь
Используется для выгрузки данных из системы. Позволяет получить значение атрибута связанного с данным объектом объекта (такие объекты отображаются на вкладке “связи”).
Имеет вид:
$<type name>.link.<type name (link)>.<attribute name>
или
$<type name>.link.<type name (link)>.<RESERVED>
- type name - название типа;
- link – означает что необходимо взять связанные объекты (объект и атрибут указываются далее);
- type name (link) - название типа связанного объекта;
- attribute name - название атрибута типа связанного объекта;
- RESERVED - это зарезервированный атрибут.
Например, чтобы получить значение атрибута name со связанного с документом TRM можно написать следующий макрос: $document.link.lmp_document_trm.name
Если атрибут имеет тип Element Book, то макрос имеет следующий вид:
$<type name>.link.<type name (link)>.<attribute name>.<linked attribute name>
или
$<type name>.link.<type name (link)>.<attribute name>.<RESERVED>
- type name - название типа;
- link – означает что необходимо взять связанные объекты (объект и атрибут указываются далее);
- type name (link) - название типа связанного объекта;
- attribute name - название атрибута типа связанного объекта (в данном случае атрибут обязательно должен быть типа Element book);
- linked attribute name - название атрибута связанного элемента справочника;
- RESERVED - это зарезервированный атрибут.
Данный макрос поддерживает комбинацию с самим собой и с макросом “Родитель”. При комбинации данного макроса с самим собой и с макросом “Родитель” часть, отвечающая за указание атрибута, отбрасывается, только у первого комбинируемого макроса.
Например, мы хотим подняться с документа на один уровень вверх (его родителя): $document.parent. Далее, получить связанный раздел (предположим в качестве раздела выступает тип section): $document.parent.link.section. Далее, получить наименование данного раздела (предположим за наименование раздела отвечает аттрибут name): $document.parent.link.section.name.
¶ Пользовательские (Запрограммированные) макросы
Используется для выгрузки и загрузки данных.
Макрос имеет формат:
$$<Name>
- Name - какое-то название макроса.
Например: $$CurrentDate – текущая дата.
В таблице ниже приведен полный список запрограммированных макросов с их описанием и местом использования.
| Макрос | Описание | Где используется | Пример вывода |
|---|---|---|---|
| $$CurrentDate | Текущая дата | Формирование CRS | |
| $$Counter | Счётчик, начиная с 1 | Формирование CRS и TRM | |
| $$Files | Путь к файлу относительно xlsx файла или полный путь. Если файлов несколько, то они перечисляются через ';'. | Массовая загрузка документации, загрузка структуры проекта | files/file.txt;files/file2.docx |
| $$SourceFile | Наименование файла (включая расширение). Если будет указан относительный или абсолютный путь, то часть отвечающая за путь будет отброшена. | Массовая загрузка документации, загрузка структуры проекта | files/source_file.pdf |
| $$ViewFile | Путь к файлу относительно xlsx файла или полный путь. Файл указанный тут будет установлен для отображения. Поддерживаются форматы: xps, pdf. | Массовая загрузка документации, загрузка структуры проекта | files/source_file.pdf |
| $$FileExtension | Расширение файла | Формирование TRM | |
| $$FileModified | Дата последнего изменения файла | Формирование TRM | |
| $$CRS | CRS связанные с документом | Формирование TRM | |
| $$FileName | Путь к файлу относительно xlsx файла | Формирование и загрузка TRM | files/file_name.pdf |
| $$Graphics | Замечание на опубликованном файле | Формирование и загрузка CRS |
¶ Логика обработки макроса $$SourceFile
Макрос
$$SourceFileне выполняет загрузку файлов, по сути данный макрос выполняет команду, представленную кнопкойСвязать с...>Исходным файлом на диске.... В качестве места где будет выполняться поиск исходного файла выступает вкладкаФайлытекущего документа.
Обработка исходных файлов осуществляется по следующей логике:
- Если исходный файл с указанным именем есть на документе в файлах (или в макросе
$$Filesуказан файл с таким именем), то связываем его; - Если нет исходного файла с указанным именем на документе в файлах, то в шаблоне загрузки выводится ошибка;
- Если в шаблоне загрузки исходный файл не указан, то ничего не происходит.
¶ Макросы шаблона письма
В шаблоне письма можно указать макросы: в тексте письма и в теме письма. Макросы оформляются по общим правилам за исключением того, что в данном случае они должны быть заключены в фигурные скобки {macro}. Пример: {$lmp_document_trm.code}, {$parent.code}. При формировании текста макросы будут заменены соответствующими значениями.