.. include:: /globals.rst .. _fd-macros-label: Macros ====== You can use macros to automate the creation of attributes based on rules inside the templates. They can also be used in trigger definitions. How to use a macro ------------------ A macro is enclosed in % and contains an LDAP attribute name. It may optionnaly states modifiers to apply to the attribute, followed by a | between modifiers and the attribute name. Some modifiers accepts parameters enclosed in [] and separated by commas. Modifiers are applied from left to right. .. code-block:: bash %sn% The value of "Last name" field, entered during account creation. Modifiers --------- **a** The **a** modifier can be used to remove accents. Examples: .. code-block:: shell %a|sn% "Last name" field returned unaccented. If "sn=Valérie" then the returned value is "Valerie" **b** The **b** modifier can be used to convert to base64. **c** The **c** modifier can be used to put a comment. An example : .. code-block:: bash %c|this is just a comment% returns an empty string. It can also be used to make a template uid unique when 2 templates have the same uid pattern: .. code-block:: bash %al|sn%%c|template1% %al|sn%%c|template2% **d** The **d** modifier can be used to generate dates and times. * First parameter is date string (defaults to “now”) * Second one is date format (defaults to “d.m.Y”, to be used in date fields). Examples: .. code-block:: bash %d|% 15.03.2017 %d[tomorrow]|% 16.03.2017 %d[today+6days]|% 21.03.2017 %d[now,l jS \of F Y h:i:s A]|% Wednesday 15th of March 2017 02:12:18 PM as POSIX date fields expects a specific format you need to add 'epoch' as second parameter to the d modifier. .. code-block:: bash %d[today+30days,epoch]|% 15.04.2017 **i** The **i** modifier can be used to have the first letter of a word in capital letters and the rest in lower case letters. Examples: .. code-block:: bash %i|sn% if our sn is "MY LAST NAME" we will have "My Last Name" in description. We do not allow element to be transformed by itself. Example : we cannot do %i|sn% in %sn% because it would make a loop. If we try it we will have this kind of error .. code-block:: bash Recursive dependency in the template fields: "givenName" cannot depend on "givenName" as "givenName" already depends on "givenName". **l** The **l** modifier can be used to return the lowercase version of the parameter. .. code-block:: bash %l|sn% "Last name" field returned in lowercase. If "sn=Valérie" then the returned value is "valérie" **p** The **p** modifier can be used to remove whitespaces. It can also be used for any search and replace based on preg_replace. For this provide 2 arguments * first one is regexp * second one is replacement string. Default values are /\s/ and empty string, to remove all whitespaces as in previous behavior. Examples: .. code-block:: bash %p|sn% "Last name" field, without whitespaces. "O Connor" becomes "OConnor". %p[/\s/,-]|sn% "Last name" field, with whitespaces replaced by dashes. "O Connor" becomes "O-Connor". **r** The **r** modifier can be used to generate random strings, for instance for passwords. It can take up to three arguments * min length * max length * character type. Third argument should be either * **l** for letters * **d** for digits * **b** for both. Default is both. The default length is 8 and if there is only one argument it will be used as a fixed length. Examples: .. code-block:: bash %r[6,10]|% a random string with a random length between 6 and 10 chars containing both letters and digits %r|% a random string of length 8 %r[12]|% a random string of length 12 %r[5,10,d]|% a random string of a random length between 5 and 10 containing only digits **s** The **s** modifier can be used to generate substrings. Examples: .. code-block:: bash %s[1,3]|sn% a substring of "Last name" field, taking 3 characters and starting at position 1. %s[0,1]|sn% the first character of "Last name" field. %s[1]|sn% the first character of "Last name" field (short syntax). %s[5]|sn% a substring of "Last name" field, taking 5 first characters. %s[2,4-8]|sn% a substring of "Last name" field, taking minimum 4 characters (more if needed for unicity) and starting at position 2. %s[4-8]|sn% a substring of "Last name" field, taking minimum 4 characters (more if needed for unicity). %s[-5,2]|sn% a substring of "Last name" field, taking 2 characters and starting 5 characters from the end. %s[-5,5]|sn% a substring of "Last name" field, taking the last 5 characters. **t** The **t** modifier can be used to return the transliterated version of the parameter. The parameters are the list of locales to use for transliteration (first one will be used by non-interactive uses of the template). Examples: .. code-block:: bash %t[de_DE]|sn% "Last name" field returned transliterated. If "sn=Süßkartoffel" then the returned value is "Suesskartoffel" Note that the locale used must be installed on the server (and web server needs to be restarted after locale installation). .. _array-modifiers: Array modifiers --------------- Array modifiers are used for multivaluated LDAP attributes and are represented as uppercase letters. If no array modifier is used on a multivaluated attribute, the "first" value is used. **C** The **C** modifier (added in version 1.0.10) returns the count of values in the attribute. It can be 0. .. code-block:: bash %C|arrayAttribute% returns the number of values in arrayAttribute **F** The **F** modifier returns the first value of the array **J** The **J** modifier returns the values joined together. It takes the separator as parameter. .. code-block:: bash %J[:]|arrayAttribute% returns the values joined and separated by : character **L** The **L** modifier returns the last value of the array Combining examples ------------------ .. code-block:: bash %al|sn% "Last name" field returned in lowercase unaccented. If "sn=Valérie" then the returned value is "valerie" .. code-block:: bash %au|sn% "Last name" field returned in uppercase unaccented. If "sn=Valérie" then the returned value is "VALERIE" .. code-block:: bash %alp|sn% "Last name" field returned in lowercase unaccented without whitespaces. If "sn=Valérie DUPONT" then the returned value is "valeriedupont" .. code-block:: bash %us[0,4]|sn% a substring of "Last name" field, taking 4 characters, starting at position 0 and converting in uppercase. If "sn=Valérie" then the returned value is "VALÉ". .. code-block:: bash %ls[1,4]|sn% a substring of "Last name" field, taking 4 characters, starting at position 1 and converting in lowercase. If "sn=Valérie" then the returned value is "alér". .. code-block:: bash %las[4]|sn% a substring of "Last name" field, taking the first 4 characters and converting in unaccented lowercase. If "sn=Valérie" then the returned value is "vale". .. code-block:: bash %r[8,8,l]u|% a random string of length 8, containing uppercase letters.