Skip to main content

Configure Tokens

Tokens provide a way to grant limited access to internal data or processes. A token represents internal data to the outside world. The token can be sent in an e-mail as a link, without sending the data it represents. The token grants access to the data through the link and can be set to expire after a configured length of time.

Navigation: Manage GT eForms 3.x > GT Technical Setup > Configure Tokens

Setting Up Token Type​

The Configure Tokens component provides the means to define a Token Type for use on a form and/or in an e-mail template. Complete the applicable fields below and click the “Save” button at the bottom of the page.

FieldUse
Token TypeEnter the reason that you need a unique identifying token
Long DescriptionEnter a detailed description of the Token Type
Expires After - DaysEnter the length of days that this token will be valid
Expires After – HoursEnter the length of hours that this token will be valid
Expires After – MinsEnter the length of time in minutes that this token will be valid
Root Package IDOptional field – Used to add code events. This field specifies an app package for custom validation, processing, and navigation of tokens of that type.
Use Email URL Override TypeOptional field – if selected, will utilize configuration from the Email URL Override Table
URL Override TypeShown if Use Override Type is checked – choice of configured URLs
Additional Appended URLOptional field – shown if Override Type selected
URLOptional field – When the token is processed, it will redirect the user to the URL entered here. The purpose is to navigate to a specific URL after a token is validated and processed

If Use Email Override Type is checked, previews the URL
Add Token to URLCheckbox to add the token itself. Fields in the Associated Fields grid below can be associated with the URL by using the “Add to URL” checkbox
Associated Fields - Field NameEnter field names. Can be form fields, PeopleSoft fields, or “GS” fields
Associated Fields - DescriptionDefaults to the field name
Associated Fields - RequiredCheckbox to mark fields required as needed
Associated Fields - Add to URLCheckbox to add these fields to the URL set on this page

Token Framework​

The Token Framework consists of the G3TOKEN app package, G3TOKEN and G3TOKEN_DATA records, G3TOKEN_TYP_TBL record, page, and component, G3TOKEN_TYPE_FLD record, G3LOADCUSTOM:TokenEvent class, WEBLIB_G3NAV.IScript2 script, and G3LOGIC_DELIVERED:SmartSource:SMARTSRC_ProcessTokenURL smart source. These work together to support the creation and handling of tokens.

G3TOKEN​

The G3TOKEN and G3TOKEN_DATA records work together with the G3TOKEN:Token class to represent live and expired tokens. Important methods of the G3TOKEN:Token class include:

G3TOKEN:Token:Start

Begin the definition of a new token of a specific token type.

G3TOKEN:Token:SetField

Set the data for a field defined in the token type. This must be called for any required fields and may be called for non-required fields.

G3TOKEN:Token:Generate

Adds the token to the database, making sure that all required fields have been defined. This completes the definition of the token, creates the token GUID, and sets the time so that it will expire as per the token type configuration. The token GUID can now be sent out into the world.

G3TOKEN:Token:Load

Load a token based on the GUID and verify that it remains valid.

G3TOKEN:Token:GetFieldValue

Get field values from the token.

G3TOKEN:Token:Validate

Validate the token. This checks for token expiration, verifies that required fields have data, and fires the OnValidate event hook to allow further custom validation. If validation fails, neither processing nor navigation will occur.

G3TOKEN:Token:Process

Fires the OnProcess event hook to allow custom token processing.

G3TOKEN:Token:Navigate

Calls GetTokenNextURL to generate the URL to navigate to. Then fires the OnNavigate event hook to allow customization of the URL. If OnNavigate returns False, no navigation will occur. Otherwise, if the URL is not empty, it then navigates to the URL.

G3LOADCUSTOM:TokenEvent​

This class adds support for Token event hooks. When creating an object of this type, the Token Type and Event method name are passed in. This class is used by G3Token:Token to fire three event hooks: OnValidate, OnProcess, and OnNavigate. Below is an example class for handling these event hooks. This class would be created in the root of the app package that is specified in the Token Type configuration.

import G3TOKEN:Token;

class TokenEvents
    method TokenEvents();
    method OnValidate(&_token As G3TOKEN:Token) Returns boolean;
    method OnProcess(&_token As G3TOKEN:Token);
    method OnNavigate(&_token As G3TOKEN:Token) Returns boolean;
end-class;

method TokenEvents
end-method;

method OnValidate
    /+ &_token as G3TOKEN:Token +/
    /+ Returns Boolean +/
    Returns True;
end-method;

method OnProcess
    /+ &_token as G3TOKEN:Token +/
end-method;

method OnNavigate
    /+ &_token as G3TOKEN:Token +/
    /+ Returns Boolean +/
    /+ After this method returns, the user will be redirected to &_token.NavigateURL
       Modify NavigateURL to affect the navigation;
       Return False to prevent Navigation from happening; +/
    Return True;
end-method;

WEBLIB_G3NAV.IScript2​

This script handles token validation, processing, and navigation when the token comes back into the system from the outside world. The token is sent to the outside world by generating a URL that points back to this script and includes the Token GUID to identify the specific token. An example link, which might be sent in a notification e-mail, would look like this:

http://www.yourdomain.com:YOUR_PORT/psp/ps/YOUR_PORTAL/YOUR_NODE/s/WEBLIB_G3NAV.ISCRIPT2.FieldFormula.IScript_Token?&G3TOKEN=6644bad8-0a52-11eb-b8bf-0d2a171ce66e

The delivered Smart Source, ProcessTokenURL, will generate the URL as shown above, based on a token that is part of an eForm and the E-Mail URL Override Table settings.

Another way to handle this would be to create a custom PPC smart source that both creates the token and generates the URL for it and use that smart source in an e-mail template. That exact pattern is how the Email Approvals feature was built.

Token Event Hooks​

Token Event Hooks allow custom PeopleCode for token validation, processing, and navigation. The Root Package ID field in the Configure Tokens component specifies the application package containing the Token Event Hooks. The application package must define a TokenEvents class containing one or more of the following methods: OnValidate, OnProcess, and OnNavigate.

OnValidate

DescriptionThis event fires after the default token validation succeeds. Return false to invalidate the token, which prevents processing and navigation. Return true to validate the token.
OverrideAdditive if return Boolean is True
Override if return Boolean is False
Path[Token Type Application Package]:TokenEvents
Declarationsmethod OnValidate(&_token as G3TOKEN:Token) returns Boolean;
Release3.30.05
Example Code
import G3TOKEN:Token;

class TokenEvents
    method OnValidate(&_token as G3TOKEN:Token) returns Boolean;
end-class;

method OnValidate
    /+ &_token as G3TOKEN:Token +/
    /+ Returns Boolean +/
    MessageBox(0, "", 0, 0, "OnValidate triggered.");
    Return True;
end-method;

OnProcess

DescriptionThis event fires after the default token processing occurs
OverrideAdditive
Path[Token Type Application Package]:TokenEvents
Declarationsmethod OnProcess(&_token as G3TOKEN:Token);
Release3.30.05
Example Code
import G3TOKEN:Token;

class TokenEvents
    method OnProcess(&_token as G3TOKEN:Token);
end-class;

method OnProcess
/+ &_token as G3TOKEN:Token +/
    MessageBox(0, "", 0, 0, "OnProcess triggered.");
end-method;

OnNavigate

DescriptionThis event fires after the default URL is constructed, but before navigation to the URL. Modify the &_token.NavigateURL property to change the URL. Return False to prevent the navigation.
OverrideAdditive if return Boolean is True Override if return Boolean is False
Path[Token Type Application Package]:TokenEvents
Declarationsmethod OnNavigate(&_token as G3TOKEN:Token) returns Boolean;
Release3.30.05
Example Code

import G3TOKEN:Token;

class TokenEvents
    method OnNavigate(&_token as G3TOKEN:Token) returns Boolean;
end-class;

method OnNavigate
    /+ &_token as G3TOKEN:Token +/
    /+ Returns Boolean +/
    MessageBox(0, "", 0, 0, "OnNavigate triggered.");
    Return True;
end-method;

G3TOKEN:Token Class​

The G3TOKEN:Token class represents live and expired tokens. Methods and properties that might be used in Token Event Hooks include:

Property/MethodDescription
property string TokenType readonly;The token type of this token
property array of string Fieldnames readonly;A list of the field names for the token type
property array of string Requiredieldnames readonly;A list of the required fields for the token type
method GetFieldValue(&FieldName As string) Returns any;Get the value of a specific field for this token