---
title: "Hyperlink Syntax and Examples"
canonical: "https://help.agiloft.com/space/HELP/43718366/Hyperlink+Syntax+and+Examples"
format: markdown
---
Hyperlinks are a critical tool for helping users quickly and easily access the system. This article details how to construct a hyperlink for your system and offers example hyperlinks to demonstrate how to use keywords to define where to take users after they log in and what actions the system should perform.

> ✅ If you manually construct a link, you also need to manually encrypt it. For information on encrypting links, see [Manually Encrypt Hyperlinks](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715001/Use+Hyperlinks+for+Access+and+Automation#manually_encrypt_hyperlinks).

# Basic Construction

Any hyperlink consists of three main components.

|  |  |
| --- | --- |
| Login URL | For example:<br>`https://<hostname>/gui2/login.jsp?<keywords>`<br>For the end user interface:<br>`https://<hostname>/gui2/login.jsp?<keywords>&euiurl=/eui2template/<template>&gui=enduser`<br>When possible, use the logical hostname for your server, such as `example.agiloft.com`, rather than the physical hostname, such as `ps108.agiloft.com`.<br>If you're using single sign-on, replace `login.jsp` with the login path for your SSO provider:<br>- For SAML: `samlssologin.jsp`
- For Windows: `sso.jsp`
- For OAuth 2.0: `oauth20sso` without `.jsp`
- For CAS: `cas-login `without `.jsp` |
| KeyID=0 | This key/value pair is always the same and is required in links. |
| Keyword pairs | Add any other necessary keywords to bring the user to the right location. See the list of keywords below. |

# Hyperlink Keywords

Keywords aren't case sensitive, but their values, such as the table or field name, are case sensitive. To find the correct case for your table, navigate to **Setup > Tables**, select your table, click Edit, and look for the Logical Table Name. To find the correct case for a field, edit its parent table, and then edit the field. Remember to use the field name, not the label.

You can use these keywords regardless of whether you are using a single sign-on hyperlink, but with single sign-on, username and password keywords are not necessary.

##### **Keyword Syntax**

```
 &keyword1=value1&keyword2=value2...
```

| **Keyword** | **Allowed Values and Examples** | **Description** |
| --- | --- | --- |
| **keyID** | 0 | The key/value pair keyID=0 is required for all login hyperlinks. |
| **kb, project, product** | Any knowledgebase name<br>*kb=Example* | These keywords specify the name of the knowledgebase that the user is logging into. They all mean exactly the same thing and are interchangeable. There is more than one keyword with this meaning for historical reasons. |
| **table** | Any logical table name<br>*Table=Case*<br>*table=person.employee* | This keyword specifies the name of the table that the user should view. In this example, it is as if the user logged on and then clicked the Cases tab.   
The Table parameter is based on the table name rather than the label.   
If the user provides a table name that is not recognized, the system logs them into the default screen with an error message:   
"Table $name not found. Please use the name of the table, rather than its label, for example Document, rather than Documents".<br>When the state=Edit:table parameter is used, you must also use the table and record parameters. For example: `&state=edit:contract&table=contract&record=202`<br>Due to the current UI design, there is no difference between specifying a table or a subtable. For example, Case.Bug takes the user to the same tab as Case. |
| **state** | - **New**<br>New:$table_name *State=New:contact*<br>OR<br>New:$table_name.$subtable   
*State=New:contact.user *<br>- **Edit**<br>*State=Edit:table_name&record_access=Edit&table=table_name&record=XXX*<br>- **Charts**<br>*State=Charts*<br>- **Main**<br>*State=Main&search=MyAssigned *<br>- ** FAQ **
  Open a record (ID=2) in edit mode<br>*example:* State=FAQ<br>- **FAQItem**<br>*State=FAQItem*<br>- **Convert**<br>*State=Convert:case* | This keyword specifies what action should be performed automatically.   
"New:$table_name" creates a new record of specified type, as in the example.<br>"Edit:$table_name" opens a record for edit in the specified table, and must be used with the parameters "table", "record", and "record_access=Edit".<br>"Charts" takes the user to the Charts tab of the Power User interface in the table specified by Table parameter.<br>"Main" takes the user to the main mode of the interface and allows specification of a search that should be automatically executed. Note the case sensitivity for this parameter: Use `State=Main` or `state=Main`, since `State=main` will not work.<br>"FAQ" takes the user to the FAQ mode of the EndUser interface and allows to specify the *table* parameter to choose the table that contains FAQ records<br>"FAQItem" takes the user to the specific FAQ record. *table* and *record* parameters are required<br>"Convert:$table_name" enables a specific record to be converted from a hyperlink. The hyperlink must include the name of a corresponding conversion action.<br>This functionality offers a way to use template records to create new records with prepopulated fields. For instance, you could provide a user with a hyperlink to "create a password reset ticket" that converts a ticket that already has the category, assigned to, and other fields filled out for a password reset request.<br>This parameter works not only in external login hyperlinks, but also in the internal hyperlinks available in the hyperlink widget in the power user home page. So you can provide multiple hyperlinks that each convert a different template ticket directly on the home page, such as: Create a Network Outage Ticket, Request a New Employee Setup, Request a Password Reset or Create a new server upgrade task. |
| **record** | Any valid record id<br>*record=123* | This parameter is mandatory for state=Edit. It identifies the record to be opened for edit by ID. |
| **expiration** | Any future date<br>expiration=05/31/2025 | This keyword defines an expiration date (MM/DD/YYYY) for anonymous links. Use it together with state=Edit |
| **field** | $fieldname:fieldvalue<br>*field=summary:test_summary* | This keyword allows you to set field values for a record in state=Edit. A hyperlink may contain several "field" parameters.   
Use the following format to modify fields:   
field=<$field_name> :<$value> |
| **exiturl** | Any url, or leaveLoggedIn<br>exiturl=https://www.sw.com | When the user logs out from Agiloft, go to the specified URL. If you want to allow the user to remain in the system after exiting the record, use the leaveLoggedIn variable instead. Note this keyword should be used only for the Power User Interface. |
| **loginurl** | Any url | If the user is unable to login to Agiloft because of an invalid username/password combination, go to this URL. If no loginurl is provided, but an exiturl is provided, the exiturl functions as the loginurl. |
| **timeouturl** | Any url | If the user's Agiloft session times out due to inactivity, go to this URL. If no timeouturl is provided but an loginurl is provided, the loginurl functions as the timeouturl |
| **logouturl** | Any url | If the user is manually logged out of Agiloft, go to this URL. If no logouturl is provided, but a timeouturl is provided, the timeouturl functions as the logouturl. |
| **cancelurl** | Any url, or leaveLoggedIn | If the user clicks the Cancel button when GUI is set to No, return to this URL. If you want to allow the user to remain in the system after exiting the record, use the leaveLoggedIn variable instead. If no cancelurl is provided, the exiturl is used. |
| **euiurl** | Any url<br>euiurl=eui2template/<x.php> | When the user logs into the End User Interface* via single-sign on,* this URL specifies where to redirect the user. For other ways to create a hyperlink to log into the end user interface, see the Examples section. |
| **gui** | - No, no
- EndUser, enduser
- Staff (default)
- No/enduser
- No/staff
- LowRes, lowres<br>*gui=no *   
* gui=LowRes*<br>*gui=no/enduser *   
*gui=enduser *   
*gui=staff* | "no" or "No" mean that only the record form, together with any pre and post HTML, is shown. The rest of the Agiloft interface is not displayed.<br>"no/enduser" or "no/staff" are just like no, but explicitly specify whether the record appears using the end user layout or the power user layout.<br>"staff" is the default and shows the full power user interface.<br>"enduser" shows the End User Interface.<br>"LowRes" directs the user to the mobile interface regardless of the device. |
| **$notmobile** | true<br>$notmobile=true | Use the parameter $notmobile to force a mobile device to access the normal desktop interface, either power or end user depending on permissions. The $notmobile parameter can also be used in login page buttons, to be sent to the browser with the login request. For example:<br>`<input type="hidden" name="$notmobile" value="true">` |
| **field= hide_btn:true** | Prevents display of the Finish&New button | This keyword is used in conjunction with GUI=No when you want the user to provide a single record, such as an employment application |
| **navigateto** | Opens a record to a specific field in the form | This keyword is used to define a specific field in the record form that is put in focus upon opening the link. You can specify different locations for power users and end users. For example:<br>`navigateto=%7Bstaff%3A%7Bfield%3A'renewal_notification_date'%7D%2 Cenduser%3A%7Bfield%3A'renewal_notification_date'%7D%7D`<br>This utilizes URL encoding in place of the {} symbols. To make the example more legible, consider how it reads when you remove the URL encoding:<br>navigateto={staff:{field:'renewal_notification_date'},enduser:{field:'renewal_notification_date'}}<br>However, the URL encoding is necessary when building the usable hyperlink.<br>This parameter can also be used in the $returnURL parameter of an [EUI macro](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43714479). |
| **user** | Any valid user login name | The keyword parameter provides the user login name. |
| **passwd, password** | Any valid password for the specified user   
*example:* passwd=bob | "passwd or password" values provide the provide the password part of a user/password combination. |
| **search** | Any valid saved search name | This keyword parameter provides the name of a saved search that is automatically executed when the user logs on.   
This parameter is always used together with the table parameter |
| **customsearch** | Any valid search | This keyword allows the user to specify the field names and values within the hotlink itself. The search uses the standard syntax ==, >=, >, <=, <, !=, (,), && and ||. However, many of these symbols have reserved meanings in HTML, so they have to be expressed using %N equivalents. For example: `CustomSearch=State% 3E=Closed%26%26Severity==Critical`<br>If the URL is used in a return URL or in the value of another query string, the reserved and excluded characters must be doubled encoded, meaning the % in the %N must also be expressed in %N format. To demonstrate, & is single-encoded as %26 and double-encoded as %2526 (%26 is the URL-encode for "&", and %25 is the URL-encode for "%").<br>Multiple conditions can be joined together using || or && symbols. It is possible to specify whether the data should be sorted in ascending or descending order by using `sortasc=$fieldname` or `sortdesc=$fieldname`.<br>If columns contain spaces, replace them with _ instead, and if names contain spaces, place them in single quotation marks. For example: `           Name_of_Related_Party='Acme Technologies Inc.'&&Party_Position=Client` |
| **record_access** | View, view   
Edit, edit   
none | This keyword causes the specified record to be opened for viewing or editing, or, if "none" is specified, causes no interface to appear at all while the hotlink is processed.<br>You might use "none" in a hotlink that is intended to change some data in Agiloft without showing the editing screen. For example, `state=Edit:Cases&record=2&fields=priority:high& record_access=none` will set the case's priority to "high" and redirect the user to the exit URL.<br>This keyword can be used together with `gui=no` to return a single record to the user without showing the rest of the Agiloft interface. |
| **locale** | de   
en   
es   
fr   
ru   
zh   
pt_BR   
SW_User_Selected_Lang | This keyword is used to define the language in which the interface should be shown to the user.   
Accepted values correspond to supported languages:   
German - de   
English - en   
Spanish - es   
French - fr   
Russian - ru   
Chinese - zh   
Brazilian Portuguese - pt_BR   
For example:   
&locale=fr   
A special value SW_User_Selected_Lang allows to log in with the same language as used for last user's session. This value will be used from now on in the email hotlinks as well.   
If no value is supplied English is assumed for backward compatibility. |

# Examples

Use these examples to see how keywords can work together. 

> ⚠️ SAML SSO users must use a Service Provider initiated hyperlink to access Agiloft. The SAML Identity Provider should be configured to include the attribute InResponseTo, and the corresponding value, in the SAML assertion response that is sent to Agiloft.

| **Action** | **Link** |
| --- | --- |
| Create a new contract record using SAML single sign-on | https://test.agiloft.com/gui2/samlssologin.jsp?State=New:contract&KB=demo |
| Open the Demo project in the EUI regardless of the user's permission set | https://test.agiloft.com/gui2/samlssologin.jsp?project=Demo&gui=enduser&state=enduser&euiURL=/eui2template/main.php |
| Open a specific record for editing using SAML single sign-on | https://test.agiloft.com/gui2/samlssologin.jsp?project=Demo&state=Edit:Contract&table=contract&record_access=view&record=+$id+&gui=no |
| Create a new Case record using SAML single sign-on | https://test.agiloft.com/gui2/login.jsp?keyID=0&kb=demo&user=admin&passwd=1&State=New:Cases.Bug_Report&table=cases&gui=no &field=description:preset%20from%20hotlink&field=solution:--%20enter%20some%20--- |
| Access the mobile interface on a desktop device. | https://test.agiloft.com/gui2/login.jsp?keyID=0&kb=KBNAME&user=USER&password=****&gui=lowres |
| Go to the Legacy End User Interface.   
When the user selects Exit, go to the URL: https://test.agiloft.com/gui2/hotlinks/test_exit_url.html   
If there is an error, for example the password is invalid, go to the URL: https://test.agiloft.com/gui2/hotlinks/test_login_url.html | https://test.agiloft.com/gui2/login.jsp?keyID=0&kb=demo&user=admin&passwd=1&State=enduser&exiturl=http://test.agiloft.com/gui2/ hotlinks/test_exit_url.html &loginurl=http://test.agiloft.com/gui2/hotlinks/test_login_url.html |
| Go to the power user interface and select the Cases table | https://test.agiloft.com/gui2/login.jsp? keyID=0 &kb=demo&user=admin&passwd=1&State=Main&table=case |
| Log in to the `main.php` page of the default End User Interface<br>When the user exits, go to the URL https://www.agiloft.com | https://example.com/gui2/eui2template/main.php?KeyID=0&KB=Demo&user=internal &password=1&exiturl=https://www.agiloft.com |
| Try to go to a non-existent table to generate a deliberate error | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &passwd=1&State=Main &table=nonexistent_contacts |
| Go to the contacts table | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &passwd=1&State=Main &table=contacts |
| Go to "contracts" table and perform the Saved Search named "company name" | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &passwd=1&State=Main &table=contracts_table &search=company%20name |
| Go to "contacts" table and search for the "test" keyword | http://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &passwd=1&State=Main&table=contact &customsearch=test |
| Submit a new bug without showing the Agiloft GUI, logoff on finish | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &passwd=1&State=New:Case &table=case&gui=no |
| Submit a new bug and show the GUI | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &passwd=1&State=New:Case &table=case |
| Go to Reports for the contact table and show the GUI | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &passwd=1&State=Charts &table=contact |
| Go to Reports for the contact table without showing the GUI | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &passwd=1&State=Charts &table=contact&gui=no |
| Submit a new record without showing the GUI, set the"description" and "solution" fields | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &passwd=1&State=New:Case &table=case&gui=no &field= description:preset%20from%20hotlink &field= solution:--%20enter%20some%20--- |
| Submit a new record without showing the GUI, set the" description "and" solution" fields and immediately exit to the specified URL without giving the user the opportunity to make any changes to the record. | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin&passwd=1&State=New:Case&table=case&gui=no &table=cases&gui=no &field=description:preset%20from%20hotlink &field= solution:--%20enter%20some%20--+&_mode=new &_unifier=50&type=30 &exiturl=http://test.agiloft.com/gui2/hotlinks/test_exit_url.html |
| Open a record (ID=2) in edit mode | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &passwd=1&State=Edit:Case &table=case&record=2 &record_access=edit |
| Open a record (ID=2) in view mode | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &passwd=1&State=Edit:Case &table=case&record=2 &record_access=view |
| Open a record (ID=2), set priority=low and exit | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &passwd=1&State=Edit:Case &table=case&record=2 &record_access=none &field=priority: low |
| Open a record (ID=3) in edit mode and change the summary and priority fields | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &passwd=1&State=Edit:Case &table=case&record=3 &record_access=edit &field=summary: from_link Tue Mar 15 15:59:09 PST 2009 &field=priority:medium |
| Open a record (ID=1) in edit mode using a temporary password that expires on 10/25/09 | https://test.agiloft.com/gui2/login.jsp?keyID=0 &kb=demo&user=admin &record_access=edit &State=Edit:Case &table=case &record=1 &expiration=10/25/09 &passwd= @@sKbNeWUkB5OEXEKRbsa9Ag% 3D% 3D |

#### Related articles

> Macro (contentbylabel)