[Bps-public-commit] RT-Extension-LDAPImport branch, useful-callbacks, updated. 0.34-8-g5e7880f
Ruslan Zakirov
ruz at bestpractical.com
Fri Feb 22 16:25:21 EST 2013
The branch, useful-callbacks has been updated
via 5e7880fdcba2fd51baaaec1a0a45fc2a2cc2b9ee (commit)
from c6accae169591aca63d57ef2a944c43fabf752c1 (commit)
Summary of changes:
Changes | 5 ++
README | 124 ++++++++++++++++++++++++++++-----
lib/RT/Extension/LDAPImport.pm | 151 +++++++++++++++++++++++++++++++++++------
3 files changed, 243 insertions(+), 37 deletions(-)
- Log -----------------------------------------------------------------
commit 5e7880fdcba2fd51baaaec1a0a45fc2a2cc2b9ee
Author: Ruslan Zakirov <ruz at bestpractical.com>
Date: Sat Feb 23 01:22:52 2013 +0400
document all the changes around callbacks in mappings
diff --git a/Changes b/Changes
index a25e19c..753667c 100644
--- a/Changes
+++ b/Changes
@@ -1,5 +1,10 @@
Revision history for RT-Extension-LDAPImport
+0.35
+ Implement better way to use functions in mappings. Old way was mostly
+ useless. It's not expected that somebody used them. See description of
+ C<$LDAPMapping> option for details.
+
0.34
Bug fix: Revert changes in 0.33_01 and _02; RT::Authen::ExternalAuth 0.13
is using RT::Record->Update now
diff --git a/README b/README
index 1f82ada..1c09920 100644
--- a/README
+++ b/README
@@ -62,17 +62,61 @@ CONFIGURATION
WorkPhone => 'telephoneNumber',
Organization => 'departmentName'});
- This provides the mapping of attributes in RT to attribute in LDAP.
- Only Name is required for RT.
+ This provides the mapping of attributes in RT to attribute(s) in
+ LDAP. Only Name is required for RT.
- The LDAP attributes can also be an arrayref of LDAP fields
+ The values in the mapping (i.e. the LDAP fields, the right hand
+ side) can be one of the following:
- WorkPhone => [qw/CompanyPhone Extension/]
+ an attribute
+ LDAP attribute to use. Only first value is used if attribute is
+ multivalue. For example:
- which will be concatenated together with a space.
+ EmailAddress => 'mail',
- The LDAP attribute can also be a subroutine reference that returns
- either an arrayref or a list of attributes.
+ an array reference
+ The LDAP attributes can also be an arrayref of LDAP fields, for
+ example:
+
+ WorkPhone => [qw/CompanyPhone Extension/]
+
+ which will be concatenated together with a space. First values
+ of each attribute are used in case they have multiple values.
+
+ a subroutine reference
+ The LDAP attribute can also be a subroutine reference that does
+ mapping, for example:
+
+ YYY => sub {
+ my %args = @_;
+ my @values = grep defined && length, $args{ldap_entry}->get_value('XXX');
+ return @values;
+ },
+
+ The subroutine should return value or list of values. The
+ following arguments are passed into the function in a hash:
+
+ self
+ Instance of this class.
+
+ ldap_entry
+ Net::LDAP::Entry instance that is currently mapped.
+
+ import
+ Boolean value indicating whether it's import or a dry run.
+ If it's dry run (import is false) then function shouldn't
+ change anything.
+
+ mapping
+ Hash reference with the currently processed mapping, eg.
+ $LDAPMapping.
+
+ rt_field and ldap_field
+ The currently processed key and value from the mapping.
+
+ result
+ Hash reference with results of completed mappings for this
+ ldap entry.
The keys in the mapping (i.e. the RT fields, the left hand side) may
be a user custom field name prefixed with "UserCF.", for example
@@ -127,11 +171,15 @@ CONFIGURATION
A mapping of RT attributes to LDAP attributes to identify group
members. Name will become the name of the group in RT, in this case
pulling from the cn attribute on the LDAP group record returned.
+ Everything besides "Member_Attr_Value" is processed according to
+ rules described in documentation for $LDAPMapping option, so value
+ can be array or code reference besides scalar.
"Member_Attr" is the field in the LDAP group record the importer
should look at for group members. These values (there may be
multiple members) will then be compared to the RT user name, which
- came from the LDAP user record.
+ came from the LDAP user record. See t/group-callbacks.t for a
+ complex example of using a code reference as value of this option.
"Member_Attr_Value", which defaults to 'dn', specifies where on the
LDAP user record the importer should look to compare the member
@@ -279,20 +327,62 @@ METHODS
object.
_build_object
- Builds up data from LDAP for importing Returns a hash of user or group
- data ready for "RT::User::Create" or "RT::Group::Create".
+ Internal method - a wrapper around "_parse_ldap_mapping" that flattens
+ results turning every value into a scalar.
+
+ The following:
+
+ [
+ [$first_value1, ... ],
+ [$first_value2],
+ $scalar_value,
+ ]
+
+ Turns into:
+
+ "$first_value1 $first_value2 $scalar_value"
+
+ Arguments are just passed into "_parse_ldap_mapping".
_parse_ldap_mapping
- Internal helper function for "import_user". If we're passed an arrayref,
- it will recurse over each of the elements in case one of them is another
- arrayref or subroutine.
+ Internal helper method that maps an LDAP entry to a hash according to
+ passed arguments. Takes named arguments:
+
+ ldap_entry
+ Net::LDAP::Entry instance that should be mapped.
+
+ only
+ Optional regular expression. If passed then only matching entries in
+ the mapping will be processed.
+
+ only
+ Optional regular expression. If passed then matching entries in the
+ mapping will be skipped.
+
+ mapping
+ Hash that defines how to map. Key defines position in the result.
+ Value can be one of the following:
+
+ If we're passed a scalar or an array reference then value is:
+
+ [
+ [value1_of_attr1, value2_of_attr1],
+ [value1_of_attr2, value2_of_attr2],
+ ]
+
+ If we're passed a subroutine reference as value or as an element of
+ array, it executes the code and returned list is pushed into results
+ array:
- If we're passed a subref, it executes the code and recurses over each of
- the returned values so that a returned array or arrayref will work.
+ [
+ @result_of_function,
+ ]
- If we're passed a scalar, returns that.
+ All arguments are passed into the subroutine as well as a few more.
+ See more in description of $LDAPMapping option.
- Returns a list of values that need to be concatenated together.
+ Returns hash reference with results, each value is an array with
+ elements either scalars or arrays as described above.
create_rt_user
Takes a hashref of args to pass to "RT::User::Create" Will try loading
diff --git a/lib/RT/Extension/LDAPImport.pm b/lib/RT/Extension/LDAPImport.pm
index 912756b..87ad64f 100644
--- a/lib/RT/Extension/LDAPImport.pm
+++ b/lib/RT/Extension/LDAPImport.pm
@@ -89,17 +89,75 @@ The LDAP search filter to apply (in this case, find all the users).
WorkPhone => 'telephoneNumber',
Organization => 'departmentName'});
-This provides the mapping of attributes in RT to attribute in LDAP.
+This provides the mapping of attributes in RT to attribute(s) in LDAP.
Only Name is required for RT.
-The LDAP attributes can also be an arrayref of LDAP fields
+The values in the mapping (i.e. the LDAP fields, the right hand side)
+can be one of the following:
+
+=over 4
+
+=item an attribute
+
+LDAP attribute to use. Only first value is used if attribute is
+multivalue. For example:
+
+ EmailAddress => 'mail',
+
+=item an array reference
+
+The LDAP attributes can also be an arrayref of LDAP fields,
+for example:
WorkPhone => [qw/CompanyPhone Extension/]
-which will be concatenated together with a space.
+which will be concatenated together with a space. First values
+of each attribute are used in case they have multiple values.
+
+=item a subroutine reference
+
+The LDAP attribute can also be a subroutine reference that does
+mapping, for example:
+
+ YYY => sub {
+ my %args = @_;
+ my @values = grep defined && length, $args{ldap_entry}->get_value('XXX');
+ return @values;
+ },
+
+The subroutine should return value or list of values. The following
+arguments are passed into the function in a hash:
+
+=over 4
+
+=item self
-The LDAP attribute can also be a subroutine reference
-that returns either an arrayref or a list of attributes.
+Instance of this class.
+
+=item ldap_entry
+
+L<Net::LDAP::Entry> instance that is currently mapped.
+
+=item import
+
+Boolean value indicating whether it's import or a dry run. If it's
+dry run (import is false) then function shouldn't change anything.
+
+=item mapping
+
+Hash reference with the currently processed mapping, eg. C<$LDAPMapping>.
+
+=item rt_field and ldap_field
+
+The currently processed key and value from the mapping.
+
+=item result
+
+Hash reference with results of completed mappings for this ldap entry.
+
+=back
+
+=back
The keys in the mapping (i.e. the RT fields, the left hand side) may be a user
custom field name prefixed with C<UserCF.>, for example C<< 'UserCF.Employee
@@ -161,12 +219,16 @@ The search filter to apply.
A mapping of RT attributes to LDAP attributes to identify group members.
Name will become the name of the group in RT, in this case pulling
-from the cn attribute on the LDAP group record returned.
+from the cn attribute on the LDAP group record returned. Everything
+besides C<Member_Attr_Value> is processed according to rules described
+in documentation for C<$LDAPMapping> option, so value can be array
+or code reference besides scalar.
C<Member_Attr> is the field in the LDAP group record the importer should
look at for group members. These values (there may be multiple members)
will then be compared to the RT user name, which came from the LDAP
-user record.
+user record. See F<t/group-callbacks.t> for a complex example of
+using a code reference as value of this option.
C<Member_Attr_Value>, which defaults to 'dn', specifies where on the LDAP
user record the importer should look to compare the member value.
@@ -575,9 +637,22 @@ sub _build_user_object {
=head2 _build_object
-Builds up data from LDAP for importing
-Returns a hash of user or group data ready for
-C<RT::User::Create> or C<RT::Group::Create>.
+Internal method - a wrapper around L</_parse_ldap_mapping>
+that flattens results turning every value into a scalar.
+
+The following:
+
+ [
+ [$first_value1, ... ],
+ [$first_value2],
+ $scalar_value,
+ ]
+
+Turns into:
+
+ "$first_value1 $first_value2 $scalar_value"
+
+Arguments are just passed into L</_parse_ldap_mapping>.
=cut
@@ -595,19 +670,55 @@ sub _build_object {
=head3 _parse_ldap_mapping
-Internal helper function for C<import_user>.
-If we're passed an arrayref, it will recurse
-over each of the elements in case one of them is
-another arrayref or subroutine.
+Internal helper method that maps an LDAP entry to a hash
+according to passed arguments. Takes named arguments:
+
+=over 4
+
+=item ldap_entry
+
+L<Net::LDAP::Entry> instance that should be mapped.
-If we're passed a subref, it executes the code
-and recurses over each of the returned values
-so that a returned array or arrayref will work.
+=item only
-If we're passed a scalar, returns that.
+Optional regular expression. If passed then only matching
+entries in the mapping will be processed.
+
+=item only
+
+Optional regular expression. If passed then matching
+entries in the mapping will be skipped.
+
+=item mapping
+
+Hash that defines how to map. Key defines position
+in the result. Value can be one of the following:
+
+If we're passed a scalar or an array reference then
+value is:
+
+ [
+ [value1_of_attr1, value2_of_attr1],
+ [value1_of_attr2, value2_of_attr2],
+ ]
+
+If we're passed a subroutine reference as value or
+as an element of array, it executes the code
+and returned list is pushed into results array:
+
+ [
+ @result_of_function,
+ ]
+
+All arguments are passed into the subroutine as well
+as a few more. See more in description of C<$LDAPMapping>
+option.
+
+=back
-Returns a list of values that need to be concatenated
-together.
+Returns hash reference with results, each value is
+an array with elements either scalars or arrays as
+described above.
=cut
-----------------------------------------------------------------------
More information about the Bps-public-commit
mailing list