Smarter by Design.Simpler for Business
ags forms
The ags forms command manages the login forms in which the user enters their identity information: the name, the title and the description of the form and the fields in it. Its panel equivalent is the Login Forms screen.
The form is the form step of the access flow. The values that the user enters pass to the flow and the authentication step uses them with the %AGS_USER_INPUT(field name) expression; for this reason the names of the form fields must fit the names that the provider expects.
Command Summary
admin@TR7LBWAF01> ags forms list # list all of them
admin@TR7LBWAF01> ags forms show <id> # show one
admin@TR7LBWAF01> ags forms add name <name> … # new form
admin@TR7LBWAF01> ags forms update id <id> … # change
admin@TR7LBWAF01> ags forms delete <id> # delete
admin@TR7LBWAF01>
Writing Order
Step 1 Create the form with its name
ags forms add name login-formThe only required field is the name, but a form without a field is not accepted: at least one form field must be given.
Step 2 Add the fields with an index
Every form field is a list item. First its type, then the settings of that type are written; the order of the fields on the screen is the index order.
--fields.0.fieldType text --fields.0.fieldName usernameStep 3 Write the texts that appear
Every text that appears to the user, such as the label, the placeholder and the help text, consists of two fields: the type and the content.
--fields.0.label.type universal --fields.0.label.text "User name"Step 4 Bind the form to the flow
The form does not work on its own; it is added to the flow of the gateway as a form step.
ags gateway update id <vService> --actions.0.actionType agsForms --actions.0.actionProfileId <form>Required Fields
| Order | Field | Status | Value |
|---|---|---|---|
| 1 | name | Required | The unique name of the form |
| — | --fields.0.… | At least one field | It appears as optional in the completion list, but a form without a field is not accepted |
The Multilingual Text Fields
Every text that appears to the user (title, description, the field label, the placeholder, the help text, the button text, the option text, the divider text, the information text) uses the same pattern: first the type, then the content according to the type.
| Type | The content field | Its meaning |
|---|---|---|
universal | .text | The same text in all the languages (the default type) |
localized | .key | The key resolved from the dictionary; the translation comes from the Dictionaries screen |
default | — | The ready text of the system is used |
none | — | The text is not shown |
# the same text in all the languages
admin@TR7LBWAF01> --title.type universal --title.text "Corporate Sign In"
# the text resolved from the dictionary
admin@TR7LBWAF01> --title.type localized --title.key login_title
admin@TR7LBWAF01>
The three parts of the text fields
Every text that uses the pattern opens into three fields on the command line. In the table below the relevant field name is written instead of <text>.
| Field | What it does | What is written after it |
|---|---|---|
--<text>.type | It selects where the text will come from | universal (the default) · localized · default · none |
--<text>.text | It writes the text directly | The text that will appear; it opens only while type universal |
--<text>.key | It calls the text from the dictionary | The key in the dictionary; it opens only while type localized |
The texts that use the pattern and their full field names:
| Text | The field names |
|---|---|
| The form title | --title.type · --title.text · --title.key |
| The form description | --description.type · --description.text · --description.key |
| The field label | --fields.N.label.type · --fields.N.label.text · --fields.N.label.key |
| The field placeholder | --fields.N.placeholder.type · --fields.N.placeholder.text · --fields.N.placeholder.key |
| The field help text | --fields.N.helpText.type · --fields.N.helpText.text · --fields.N.helpText.key |
| The option text | --fields.N.options.M.text.type · --fields.N.options.M.text.text · --fields.N.options.M.text.key |
| The submit button text | --fields.N.buttonText.type · --fields.N.buttonText.text · --fields.N.buttonText.key |
| The button text in a button group | --fields.N.buttons.M.text.type · --fields.N.buttons.M.text.text · --fields.N.buttons.M.text.key |
| The information text | --fields.N.content.type · --fields.N.content.text · --fields.N.content.key |
| The divider text | --fields.N.dividerText.type · --fields.N.dividerText.text · --fields.N.dividerText.key |
The Field Types
| Field | What it does | What is written after it |
|---|---|---|
--fields.N.fieldType | It selects the type of the form field; the settings specific to the type open according to this | One of the eighteen values below |
The additional settings change according to the type:
fieldType | The panel name | The settings specific to the type |
|---|---|---|
text | Text | validationPattern · minLength · maxLength |
password | Password | minLength · maxLength |
email | — | |
number | Number | min · max |
textarea | Multi-line text | rows (the default 4) · minLength · maxLength |
select | Single select | options.N.value · options.N.text.… |
multipleSelect | Multiple select | options.N.value · options.N.text.… |
file | File | accept · maxSize |
date · time · datetime | Date · Time · Date and time | — |
checkbox | Checkbox | — |
hidden | Hidden field | hiddenValue |
submitButton | Submit button | buttonText.… · buttonStyle · buttonIcon · submitBehavior · submitData.N.key · submitData.N.value |
infoText | Information text | content.… |
divider | Divider | dividerText.… |
customHtml | HTML content | htmlContent |
buttonGroup | Button group | layout · columns · buttons.N.… |
The sub object fields are listed in every type
The sub fields such as options, buttons, submitData and content appear in the completion list independently of the field type. Writing them in an unrelated type does not do anything; the table above shows which setting belongs to which type.
The Settings Common to All the Fields
| Setting | Default | Notes |
|---|---|---|
--fields.N.fieldName | — | The name of the field in the flow; it begins with a letter and contains letters, digits and an underscore. It is not present in the divider, infoText and customHtml types |
--fields.N.label.… · --fields.N.placeholder.… · --fields.N.helpText.… | The text pattern | The label, the placeholder and the help text |
--fields.N.required | false | Whether it is obligatory for the user to fill it in; it is not present in the button, divider, information text and hidden fields |
--fields.N.defaultValue | — | The value that the field will carry when it opens; it is not present in the button, divider, information text, hidden field and button group |
--fields.N.cond | Without a condition | The field is shown only when the condition is met |
--fields.N.assignToUserFields.0 | userId | The user session field to which the value of the field will be copied; it is valid in the text, email, number, select and hidden types |
The --fields.N.assignToUserFields.N field takes the following values: userId, username, email, displayName, firstName, lastName, phone, picture, locale, timezone, company, department, title, employeeId, groups.
The --fields.N.validationPattern field is valid only in the text type and takes the following values: None, email, domain, ip, port, url, alphanumeric, numeric.
The Full List of the Fields Specific to the Type
The full field names of the settings given briefly in the table above, what they do and in which field type they open:
| Field | What it does | What is written after it | In which type |
|---|---|---|---|
--fields.N.validationPattern | It checks the format of the value entered | None · email · domain · ip · port · url · alphanumeric · numeric | text |
--fields.N.minLength · --fields.N.maxLength | It limits the shortest and the longest length of the text to be entered | The number of characters | text · password · textarea |
--fields.N.rows | It determines how many rows of the multi-line field will appear | The number of rows (the default 4) | textarea |
--fields.N.min · --fields.N.max | It determines the lower and the upper limit of the number to be entered | A number | number |
--fields.N.options.M.value | It determines the value that the option will carry in the background | The value; at least one option is needed | select · multipleSelect |
--fields.N.accept | It limits the file types that can be uploaded | A file type list, for example .pdf,.png | file |
--fields.N.maxSize | It determines the biggest file size that can be uploaded | The size | file |
--fields.N.buttonStyle | It selects the appearance of the submit button | primary (the default) · secondary · danger · success · custom | submitButton |
--fields.N.buttonIcon | It determines the icon of the submit button | The icon name | submitButton |
--fields.N.submitBehavior | It selects which data will be carried in the submission | fullForm the whole of the form (the default) · merge it adds additional data to the form · override it sends only the data given | submitButton |
--fields.N.submitData.M.key · --fields.N.submitData.M.value | It writes the name and value pairs to be added to the submission | The field name and its value | submitButton, while submitBehavior is merge or override |
--fields.N.htmlContent | It writes the HTML content to be embedded into the form | The HTML text | customHtml |
--fields.N.hiddenValue | It writes the value that the hidden field will carry | The value | hidden |
--fields.N.layout | It selects how the buttons in the button group will be arranged | horizontal (the default) · vertical · grid | buttonGroup |
--fields.N.columns | It determines the number of columns in the grid layout | A number (the default 2); it opens only while --fields.N.layout grid | buttonGroup |
--fields.N.buttons.M.value | It determines the value that will be sent when the button is pressed | The value | buttonGroup |
--fields.N.buttons.M.cond | It makes the button appear only in a certain case | A condition expression | buttonGroup |
--fields.N.buttons.M.icon | It determines the icon of the button | The icon name | buttonGroup |
--fields.N.buttons.M.style | It selects the appearance of the button | primary · secondary (the default) · danger · success · custom | buttonGroup |
--fields.N.buttons.M.backgroundColor · --fields.N.buttons.M.textColor | It determines the background and the text color of the button | A color value; it is used when style custom is selected | buttonGroup |
Examples
admin@TR7LBWAF01> ags forms add name login-form \
--title.type universal --title.text "Corporate Sign In" \
--fields.0.fieldType text --fields.0.fieldName username \
--fields.0.label.type universal --fields.0.label.text "User name" --fields.0.required true \
--fields.1.fieldType password --fields.1.fieldName password \
--fields.1.label.type universal --fields.1.label.text "Password" --fields.1.required true \
--fields.2.fieldType submitButton --fields.2.fieldName submit \
--fields.2.buttonText.type universal --fields.2.buttonText.text "Sign in"
admin@TR7LBWAF01>
admin@TR7LBWAF01> ags forms update id <kimlik> \
--fields.3.fieldType select --fields.3.fieldName department \
--fields.3.options.0.value it --fields.3.options.0.text.type universal --fields.3.options.0.text.text "Information Technology" \
--fields.3.options.1.value hr --fields.3.options.1.text.type universal --fields.3.options.1.text.text "Human Resources" \
--fields.3.assignToUserFields.0 department
admin@TR7LBWAF01>
admin@TR7LBWAF01> ags forms update id <kimlik> \
--fields.4.fieldType text --fields.4.fieldName institution_code \
--fields.4.validationPattern alphanumeric --fields.4.minLength 4 --fields.4.maxLength 12
admin@TR7LBWAF01>
Updating and Deleting
The updating asks for the identifier with the id field and changes only the fields written. The field list is updated with the index; --fields.delete empties the whole of the list.
admin@TR7LBWAF01> ags forms update id <id> --fields.0.label.text "E-mail address"
admin@TR7LBWAF01> ags forms update id <id> --fields.delete # remove all the fields
admin@TR7LBWAF01> ags forms delete <kimlik>
admin@TR7LBWAF01>
Things to Know
- The field names must fit the provider. The authentication providers expect the names
usernameandpasswordby default; if a different name will be used, the user name and password expressions of the provider must be updated as well. - A form without a field is not accepted. Even if the field list appears as optional in the completion list, at least one field is needed; a command without a field returns an error.
- The order is the index order. The order in which the fields appear in the form is according to the
--fields.0,--fields.1… indexes; adding a field in between requires the indexes to be written again. - The texts with spaces require quotation marks. The values that contain a space such as the label and the title are written with double quotation marks.
- The form does not work on its own. It is not used until it is added to the flow of the gateway as a form step.
