How to create an application form - long version

Back to Perun main page

VO MANAGER role needed

Please note: There is also a short, more straightforward version of documentation.

Application workflow

• User display a form
  • he is not a member - first form s displayed
  • he is already member -- application to extend a membership is displayed
  • application has prefilled items with data taken from perun and federation (perun data has precedence over federation)
• User submits an application form (NEW state)
  • application data is saved in DB, KDC logins are reserved
  • VO manager receives a notification when new application form is submitted
  • user receives a notification when he submits an application form
• Email verification
  • e-mail is not required in application form or it is prefilled from federation data
    • application is verified automatically (move to state VERIFIED)
  • user sets new email (different from the one from federation)
    • email notification with link to email verification is send to user
    • when user click on the verification link, application is verified (move to state VERIFIED)
• Approval and rejection of application
  • manager approves (state APPROVED) or rejects (state REJECTED) application in GUI
  • approval
    • first application form - creates new VO member
    • application to extend a membership - extends a membership in VO
    • notification sent to user via email about approval
    • after approval, no more first (INITIAL) form can be filled by the user
  • rejection
    • KDC login reservation is removed
    • notification sent to user via email about rejection
    • user can submit new first (INITIAL) application

VO application form

• Every VO has only one form with manual or automatic approval (it can be set).
• Division into first (INITIAL) and extension (EXTENSION) application form is based on items in the form. Each item has set whether is shown in the first form or in the extension form or in both.
• If user is not VO member, first form is displayed. Otherwise, extension form is displayed.
• Until first application is approved, user can not submit another form. Extension applications can user submit as many as he needs.
• Membership rules in VO can restrict possibility to submit application form in VO (e.g. VO attribute membershipExpirationRules requires concrete user LoA, assigns period extension or length of membership).

Group application form

• Every group in VO can have unique application form (it must be created in Group manager section).
• When first application to group is submitted, not being member of parental VO user automatically submits a first application to the VO.
• After approval, user is automatically incorporated into the group.
• As far as groups are concerned, extension application form can not be submitted (membership lasts until member is in parental VO or until member is manually removed from group).
• Group application form has own email notification different from VO's notification (to have both same, duplicate notification must be created).

Attributes in VO application form

Attributes must be set on the page VO manager - Settings (Add button). Same attributes are required in application to groups.

• Email address "From" - Email address used as “from” for all email notification to VO or group users.
• Email address "To" - Mailing list used as “to” for all email notification to VO or group manager.
• URL logo VO - URL address (including http://) to picture with VO logo (it would be shown in the top of application form).
  • The picture with VO logo will also appear in the group application form.

Modules

• Module that do additional action with new user (add into group, set default attribute values, etc.) can be programmed to every application form (both VO and group).
• Module is called after three actions: submitting, approval or rejection of application are successfully finished.
• Name of module class is set in GUI in application configuration (button Settings).

Automatic approval

• If approval is automatic, it is done right after submitting of application by user. Verification is required; therefore it may wait to manual verification of email by user.
• Automatic approval is divided into initial application form and extension application form.

Redirecting from application form

3 params ("&param=text") to redirect could be inserted into URL of application form. Parameter value is URL of web page to where redirect.

targetnew - Redirecting runs automatically after sending and receiving new (INITIAL) form. When error occurred, redirecting can not proceed, error alert appears on the page.

targetextended - Redirecting runs automatically after sending and receiving (EXTENSION) application form. When error occurred, redirecting can not proceed, error alert appears on the page.

targetexisting - Redirecting runs automatically after form loading, if user is already VO/group member and it is not a period to extend a membership (VO attribute Membership expiration rules , item gracePeriod - sets number of months before expiration date when user can extend his membership.

Work with items in the form

All changes in form are just temporary and are saved only after pressing Save in the main bar. Save rewrites the form as a whole in the DB! When error occurred, no change is saved!

How to add an item in a form

• Button Add in the main bar solves this task. Creation has two phases and newly created items are green-colored in the example.

Item attributes creation

Short name - Is compulsory attribute to identify the item. If no description is added, short name is listed in the form.

Input widget - Sets the type of input. Detailed description is below.

Insert after - Insert new item after another item or on the very beginning of form.

Item types

Input text field

- Free short text (max. 512 characters).

WARNING: If a member want to fill a phone number, the number must begin with +.

Input text multi-line field

- Free long text (max. 1024 characters).

Single value selection from list

- PullDown menu, user can only select one from the answers.

Single value selection with opt. custom value

- PullDown menu with option “- other value -” to enable inserting other value (as textfield) by user.

Checkbox

- Input element of type checkbox is rendered by default as square boxes that can be checked.

Input text field for username/password

- Editable fields, but when USERNAME is prefilled, it can not be changed and field PASSWORD is hidden. The relationship between both items is created by value of parameter Perun destination attribute or federation attribute (but just when filled with data from federation). Attribute name is connected with login in namespace or parameter name from federation, e.g. urn:perun:user:attribute-def:def:login-namespace:einfra or krbPrincipalName.

Different logins for different namespace are allowed, but it is necessary to keep a relationship via parameter and order of items. If login is empty in the form and it is typed by user, dynamic control of login availability check it.

Input text field for email

- Editable field to set an email to verification. All notifications are sent to this email. When is filled value same as the verified one, email is consider verified.

Custom submit button

- Submit button in the form. Label sets text in the button.

Submit button with auto-submit

- If input in a form is valid, it's automatically submitted without user interaction.

Custom HTML text

- Any HTML-formatted text, e.g. general instructions for application form. Content is saved into parameter label depending on language.

Header

- Custom text displayed as heading.

Selection of timezone

- Selection box pre-filled with available timezones like: Europe/Prague.

Hidden input text pre-filled from external source

- Hidden text field containing values taken from federation, hidden for user but visible for VO manager. It serves to save data taken from federation.

Input text pre-filled from external source

- Uneditable text field containing values taken from federation.

Configuration

Common parameters are:

Required - Item is required and user must fill it. Asterisk after item's name marks the item in the form.

Regular expression - If filled, item value is checked with regexp in field.

Federation attribute - Connection of item to data from federation. Item is pre-filled if data from federation is available. Allowed values are:

• displayName (displayed name),
• cn (common name),
• mail (email address),
• o (organisation),
• loa (level of assurance),
• eppn (mail?),
• givenName (given name),
• sn (surname).

Destination attribute - Relation to attribute in Perun system. Value submitted by user is saved to the particular attribute and pre-fills items in application. Only attributes for entities user and member can be saved and pre-filled.

Use in application types - Sets which type of application (initial or extension) contains an item.

Language bookmark:

Label - Main description shown to user. When missing, Short name is used instead. Help - Text shown as help for an item.

Error - Text that appears when item value does not match with Regular expression.

Box contents - Predefined values for items with type SELECTIONBOX a COMBOBOX that user can select. Value saved in DB and description are specified.

How to delete, edit and order items

Item is deleted by button Delete placed in the line with item definition. Item is marked to remove, but removed is when form is saved (by click on Save). Until the form is saved, button Undelete reverse the process. Before you delete an item, consider a possibility simply just to hide an item from both types of form (initial and extension).

Order of items are defined in the overview of all items. Order can be changed by buttons with arrows. Button Edit enables to edit of all available parameters, editing is confirmed by button OK. All changes are saved after button Save is pressed.

Application overview

Button Preview... serves to see an overview from user's point of view. Overview use cached information so to see changes in form, overview must be closed and reopen. Overview implements validation items with regexp, but functionalities to send a form or to pre-fill item automatically do not work. Overview supports switching between type (INITIAL, EXTENSION) and language of form (Czech, English).

E-mail notification

Button E-mail notifications serves to configure email notifications. E-mail definitions for specified actions during registration process can be added, supporting also more language mutations, can be switched on/off and special variables serves to substitute them with actual data depending on user and his application form. When error occurred, mail is not send and error is logged.

Language

Notification language is set by any item of form with relationship to attribute urn:perun:user:attribute-def:def:preferredLanguage. When this item is missing and user has an account in Perun, value is taken from his attribute, otherwise English version is used.

Notification type

Definition must be created for initial and extension application separately. When definition does not exist, mail is not send.

Created / user

- Confirmation of submitting application form by user. It is send to the user to the first email address inserted into field VALIDATED_EMAIL. When address or array do not exist in the form, mail preferred by user is used.

Created / manager

- Notification to VO manager about new application. It contains link to application's detail to approve or deny it. When during process errors occurred, list of errors is attached. These errors can be sent to solve by perun admin.

Mail validation / user

- Notification containing link to validation to check an email address. This email is sent just in case unapproved email is in array VALIDATED_EMAIL (its value is different from pre-filled).

Approved / user

- Notification to user that his application was accepted and he became VO member (his membership was extended).

Rejected / user

- Notification to user that his application was rejected by VO manager. During rejection in GUI, reason of rejection can be inserted and consequently sent as part of notification.

Dynamic content substitution

There are several keywords to use in email to substitute with actual data. These keywords can be used in both email subject and text with only one exception {validationLink}, which can be used only in email text with type MAIL_VALIDATION ! When keyword misses a value or error occurred, free space is inserted instead.

• {appId} - Application number.
• {actor} - Login of user who submit an application (login used to logn in GUI).
• {extSource} - External resource from where user comes (used to logn in GUI).
• {firstName} - First name of user related to form item with perun destination attribute urn:perun:user:attribute-def:core:firstName.
• {lastName} - Last name of user related to form item with perun destination attribute urn:perun:user:attribute-def:core:lastName.
• {displayName} - Full user name with academic degrees related to form item with perun destination attribute urn:perun:user:attribute-def:core:displayName.
• {login-[namespace]} - User login in the namespace related to form item with type USERNAME with perun destination attribute urn:perun:user:attribute-def:def:loginNamespace:[namespace]. [namespace] Can be substituted with values: einfra, meta, egi-ui, cesnet, mu. E.g.: {login-einfra}.
• {membershipExpiration} - Expiration date after creation or extension VO membership. It is taken from already existing user so it is not necessary to be in application form. It is related to member attribute urn:perun:member:attribute-def:def:membershipExpiration.
• {voName} - Full name of VO to which application belongs.
• {groupName} - Full name of group to which application belongs.
• {mailFooter} - General mail footer used for emails for VO, related to value of attribute urn:perun:vo:attribute-def:def:mailFooter that should be set only in GUI interface in order not to lost formating.
• {appGuiUrl} - Link to register GUI of Perun system.
• {appDetailUrlFed}, {appDetailUrlKerb}, {appDetailUrlCert} - Links to details of application form with different type of authentication to be used by VO manager.
• {perunGuiUrlFed}, {perunGuiUrlKerb}, {perunGuiUrlCert} - Link to Perun GUI with different type of authentication.
  • Fed = federation
  • Kerb = kerberos
  • Cert = certificate
• {errors} - List of errors that occurred during whole process. Now only sent in notification to VO manager about application creation.
• {customMessage} - Customizable message to add to specified type of notification to user. At the moment used only in notification to user about application rejection (it contains specific reason written by VO manager in GUI during process of rejection).