Маппинги#

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

Содержание#

• Основные понятия

  • Источник

  • Цель

  • Выражение

  • Условие маппинга

• Другие настройки маппингов

  • Переменные в маппингах

  • Ограничения

  • Параметры состояния в контексте маппингов

  • Сила маппинга

  • Авторитетность

Основные понятия#

Маппинг состоит из четырех основных элементов:

• Источник — источник данных, из которого маппинг берет данные для обработки.

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

• Условие — настройки, управляющие движением данных. В этом блоке определяется, будут ли данные передаваться, как, когда, при каких условиях.

• Цель — целевой ресурс, в который должны быть переданы данные.

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

<mapping>
    <source>
        <path>$focus/givenName</path>
    </source>
    <source>
        <path>$focus/familyName</path>
    </source>
    <expression>
        <script>
            <code>givenName + ' ' + familyName</code>
        </script>
    </expression>
    <condition>
        <script>
            <code>givenName != null &amp;&amp; familyName != null</code>
        </script>
    </condition>
    <target>
        <path>$projection/attributes/cn</path>
    </target>
</mapping>

Рассмотрим подробнее каждый из элементов.

Источник#

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

Чтобы маппинг работал корректно, у него должен быть подходящий источник. Так, для входящих (inbound) маппингов, то есть когда данные двигаются из внешнего источника в систему IDM, источником данных маппинга должен быть внешний ресурс. И наоборот, для исходящего (outbound) маппинга источником должен быть IDM.

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

Таким образом, мы можем увидеть, что пример выше — действительно исходящий маппинг, так как в источнике используется переменная $focus.

Источники являются относительными, что выражается в нескольких особенностях.

Во-первых, маппинги реагируют на изменения данных в источниках, и запускают перерасчет данных при необходимости. Так, для примера выше маппинг запустит перерасчет, если любое из двух значений (givenName и familyName) изменится, или если будет запущен процесс полной реконсиляции.

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

Сами источники содержат не только свои значения, но и предыдущее значение, и дельту изменений. Это позволяет маппингу делать умный перерасчет, обрабатывая только изменившиеся значения. Наличие дельты также позволяет маппингу обрабатывать только те данные, которые реально были изменены.

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

Имя источника#

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

По умолчанию в качестве имени источника берется последний сегмент пути источника. Так, например, источник с путем $focus/activation/administrativeStatus будет по умолчанию доступен в скриптах как administrativeStatus.

Однако существуют пути, которые одинаково заканчиваются, например $focus/activation/administrativeStatus и $focus/assignment/activation/administrativeStatus. Если оба этих объекта будут использоваться как источники маппинга с именами по умолчанию, то возникнут ошибки. Поэтому один из этих параметров необходимо переименовать.

Для этого в определении источника доступен дополнительный элемент <name>, с помощью которого можно эксплицитно задать имя маппинга, по которому он будет вызываться в скриптах. Например:

<source>
    <name>lastName</name>
    <path>$focus/familyName</path>
</source>

В случаях, когда основные входящие данные маппинга из одного источника, их так же можно вызывать в функции по имени input. Например, это будет верно для входящего маппинга на одиночный параметр, или для самостоятельного выражений без источника, так как в таком случае нет какого-либо пути, из которого можно было бы получить имя для входящих данных.

Область определения маппинга#

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

По умолчанию, область определения маппинга не ограничена. Это значит, что все возможные значения, передаваемые из источника, будут обработаны маппингом. Однако область определения можно уточнить при помощи объявления элемента <set> в источнике:

<mapping>
  <authoritative>true</authoritative>
  <source>
    <path>organization</path>
    <set>
      <condition>
        <script>
          <code>basic.stringify(organization)?.startsWith("AUTO-")</code>
        </script>
      </condition>
    </set>
  </source>
  ...
</mapping>

Такой маппинг будет обрабатывать только те значения из источника, которые начинаются с AUTO-.

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

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

Цель#

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

Указание цели маппинга не просто определяет, куда будет передаваться результат работы маппинга. Цель связывает параметр с маппингом, косвенно определяя тип исходящих данных, их кратность, и даже возможно множество допустимых результатов обработки. Цель маппинга определяет, как обрабатываются изменения и как формируются дельты.

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

<target>
    <path>fullName</path>
</target>

Обратите внимание — у маппинга может быть только одна цель, в отличие от источников.

Область значений маппинга#

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

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

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

Область значений маппинга по умолчанию пуста, и поэтому большинство маппингов считается неавторитетным. Фактически это значит, что при отсутствии прямого конфликта, все исходящие данные маппинга будут занесены в целевой объект, и могут быть в дальнейшем удалены, при соблюдении принципа релятивности маппингов.

Установить область значений для цели маппинга можно через элемент <set>:

 <mapping>
            <expression>
                ...
            </expression>
            <target>
                <set>
                    <predefined>all</predefined>
                </set>
            </target>

Возможные значения для установки области значений:

• Предопределенные переменные. Эти значения устанавливаются через элемент <predefined>:

  • all — все значения. Такой маппинг считается авторитетным для всех значений, будет удалять все значения, которые не являются допустимыми, то есть не являются результатами вычисления маппингом.

  • none — никакие значения. Такой маппинг будет неавторитетным для всех значений. Это значит, что маппинг не удаляет никаких значений, кроме тех случаев, когда удаление значения является результатом обработки маппинга и работы релятивности маппингов.

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

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

Например:

        <mapping>
  <expression>
    ...
  </expression>
  <target>
    <set>
      <condition>
        <script>
          <code>
            import com.evolveum.midpoint.schema.constants.*
            input.targetRef != null &amp;&amp; input.targetRef.relation == SchemaConstants.ORG_MANAGER
          </code>
        </script>
      </condition>
    </set>
  </target>

Источники и цели по умолчанию#

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

Выражение#

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

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

Важно!

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

Выражения используются не только в маппингах. Подробнее о построении выражений смотрите в разделе Выражения.

Условие#

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

Например:

<inbound>
    <expression>...</expression>
    <target>...</target>
    <condition>
        <script>
            <code>basic.isEmpty(input)</code>
        </script>
    </condition>
</inbound>

Маппинг выше запишет свое значение в цель только если входящие данные маппинга (переменная input) не пустые.

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

Например:

<inbound>
    <expression>
        <value>
            <targetRef oid="58f6e350-88d3-11ec-9cf0-8f0fa20c5fc3" type="RoleType"/>
        </value>
    </expression>
    <target>assignment</target>
    <condition>
        <script>
            <code>hrJobCode == "1234"</code>
        </script>
    </condition>
</inbound>

Маппинг выше добавляет юзеру назначение, если параметр hrJobCobe имеет значение 1234, и удаляет его если значение отличается.

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

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

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

Другие настройки маппингов#

Переменные в маппингах#

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

Переменные и источники маппингов похожи друг на друга в том, как они используются, и в своем поведении при вычислении маппинга. И переменные, и источники приводятся как переменные в коде скрипта. Переменные могут быть релятивистичными, например, при вычислении дельты маппинга, переменная $focus будет содержать старый объект юзера при обработке старого значения источника, и новый объект при обработке нового значения источника. Однако у переменных и источников есть важные различия:

• Изменения в значениях переменных не приводят к запуску перерасчета маппинга.

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

• Маппинги обрабатывают каждое значение источника по отдельности, в то время как переменные предоставляются "as is", в виде квази-статичного значения, содержащего целый объект.

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

Исходя из этого, источники следует использовать для:

• Основных входящих данных, которые скорее всего будут изменяться. Например, фамилия в маппинге, вычисляющем ФИО пользователя.

• Данных, на изменение которых необходимо незамедлительно реагировать. Например, код занимаемой должности в HR системе, который используется для автоматического определения назначений на роли.

С другой стороны, переменные используются для:

• Конфигурационных данных, которые редко изменяются. Например, базовый контекст LDAP или имя организации, которые можно хранить в расширении объекта конфигурации системы, который, в свою очередь, всегда доступен как переменная в выражениях.

• Диагностики, например вывода имени ресурса вместо OID в записях журнала.

Использование переменных#

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

Так, в скриптах (которые используют Groovy) переменные указываются как простые имена:

givenName + ' ' + familyName

В то время, как переменные в выражениях путей объектов (язык Prism) указываются с префиксом $:

$givenName

Объекты в переменных#

Некоторые переменные могут содержать простые значения, например строки. Однако IDM в основном работает с объектами — пользователями, ролями, ресурсами. Поэтому многие переменные содержат структуры данных Prism, представляющие объекты.

Получить доступ к параметрам объектов можно по модели работы объектно-ориентированного программирования. В скриптах на Groovy или Python параметры обрабатываются как же, как и у объектов Java:

focus.getGivenName()

Если объекты имеют глубокую иерархию параметров, при работе с ними следует быть осторожным с null значениями. В Groovy для этого есть оператор безопасной навигации ?:

focus?.getActivation()?.getAdministrativeStatus()

В путях объектов используется язык с особым синтаксисом для работы с объектами Prism. Этот язык очень эффективно работает с путями объектов, и используется во многих конфигурационных файлах IDM. Например:

$focus/activation/administrativeStatus

Список переменных#

Ограничения#

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

Ограничения по каналу#

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

Например:

<inbound>
    <strength>strong</strength>
    <channel>http://midpoint.evolveum.com/xml/ns/public/provisioning/channels-3#import</channel>
    <expression>
        ...
    </expression>
    ...
</inbound>

Для управления ограничением по каналу доступно два элемента:

• <channel> — Ограничивает использование маппинга, разрешая его только в контексте указанного канала.

• <exceptChannel> — Ограничивает использование маппинга, запрещая его только в контексте указанного канала.

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

Каналы#

Каналы определяются IDM. Это внутренние URL, используемые IDM для общих задач, таких, как импорт или синхронизация.

Ограничения по времени#

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

Например:

The mapping below will be applied only in time interval that starts 10 day after the disableTimestamp and ends 3 months after disableTimestamp.

<mapping>
    <timeFrom>
        <referenceTime>
            <path>activation/disableTimestamp</path>
        </referenceTime>
        <offset>P10D</offset>
    </timeFrom>
    <timeTo>
        <referenceTime>
            <path>activation/disableTimestamp</path>
        </referenceTime>
        <offset>P3M</offset>
    </timeTo>
    <expression>
        <asIs/>
    </expression>
</mapping>

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

Ограничение по времени состоит из двух элементов:

• <referenceTime> определяет момент во времени, который является точкой отсчета. Значение в элементе должно быть путем к параметру, в который записан timestamp.

• <offset> задает смещение относительно точки отсчета в любую сторону. Элемент задается в формате XSD duration data (ISO 8601).

Итоговая точка времени, которая будет использоваться в ограничении получается из применения <offset> к <referenceTime>.

Любая комбинация ограничений по времени <timeFrom> и <timeTo> (оба, ни одного, один из) может быть использована в маппинге.

Выражения в ограничениях по времени#

Точку отсчета времени для ограничений по времени можно определить скриптовым выражением:

    <mapping>
        <timeFrom>
            <expression>
                <script>
                    <code>
                        def createTimestamp = focus?.metadata?.createTimestamp
                        def timestamp = basic.addDuration(createTimestamp, "P3M")
                        return basic.roundDownToMidnight(timestamp)
                    </code>
                </script>
            </expression>
        </timeFrom>
        ...
    </mapping>

Пример выше вернет timestamp, который основан на времени создания объекта, сдвинут во времени на три месяца после этого времени, и округлен до полуночи.

Если выражение возвращает null, то ограничение будет считаться неудовлетворенным, и маппинг будет проигнорирован.

Параметры состояния в контексте маппингов#

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

<outbound>
  <source>
    <path>title</path>
  </source>
  <expression>
    <script>
      <code>
        ...
        midpoint.getMapping().setStateProperty("reduceRange", true)
        ...
      </code>
    </script>
  </expression>
  <target>
    <set>
      <condition>
        <script>
          <code>
            if (midpoint.getMapping().getStateProperty("reduceRange")) {
            ....
            }
          </code>
        </script>
      </condition>
    </set>
  </target>
</outbound>

Сила маппинга#

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

По умолчанию все маппинги имеют силу normal. Сила задается элементом <strength>:

<inbound>
    <strength>strong</strength>
    ...
</inbound>

Обратите внимание, только сильные маппинги (strong) будут гарантированно перезаписывать значения во время реконсиляции. Это сделано потому, что маппинги основаны на обработке релятивных изменений между ресурсами и IDM, а во время реконсиляции изменений в источниках данных как правило нет. Поэтому нет причины применять маппинги normal силы.

Также рекомендуется переносить системы на IDM с маппингами normal силы, чтобы избежать уничтожения данных в целевых системах. Когда переход завершен и политики окончательно определены и протестированы, тогда обычно маппинги переключаются на strong.

Авторитетность#

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

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

По умолчанию маппинг является авторитетным, то есть значение элемента <authoritative> = true.

Например:

<mapping>
<authoritative>true</authoritative>
  <source>
    <path>organization</path>
    <set>
      <condition>
        <script>
          <code>basic.stringify(organization)?.startsWith("AUTO-")</code>
        </script>
      </condition>
    </set>
  </source>
</mapping>