RETS Change Proposal: Session information tokens

Author: Libor Viktorin

Organization: MarketLinx

Telephone Number: (865) 470-1627

Address: 1400 Centerpoint Blvd. Suite 100; Knoxville, TN  37932

Email: lviktorin@marketlinx.com

Status: Proposal

Date: July 20, 2007

Version: 1.7

1. Synopsis

 

2. Rationale

Validation expressions currently use several special operand tokens (see table 11-34) to account for data such as UserID, BrokerCode etc, describing the current user. The values for these tokens are set in the Login transaction response.

With broader use of the update transaction and validation, it's becoming clear that the current tokens may not be sufficient for all situations. RETS needs a way to let the server provide any information pertaining to the current session. This document proposes a way to do it. 

3. Proposal

In chapter 4.6, the normal "OK" response format should be given as:

<RETS 1*SP ReplyCode=quoted-reply-code
          1*SP ReplyText=quoted-string *SP >
<RETS-RESPONSE>
[member-name-key ]
[user-info-key ]
[broker-key ]
[metadata-ver-key ]
[metadata-timestamp-key ]
[min-metadata-timestamp-key ]
[ office-list-key ]
[ balance-key ]
[ timeout-key ]
[ pwd-expire-key ]
*( info-token-key )
capability-url-list
</RETS-RESPONSE> [<RETS-STATUS [1*SP ReplyCode=quoted-end-reply-code
  1*SP ReplyText=quoted-string * SP]/>
</RETS> CRLF   


In each of chapters 4.7.1, 4.7.2, 4.7.3, 4.7.4, 4.8.1, 4.8.2 the following should be added:

This argument is deprecated and will be replaced by the Session Information Token (see 4.7.5).
Servers that claim to be backwards compatible with previous versions of RETS MUST still use this argument, but MUST also send the same information in a info-token-key.
Servers that do not claim to be backwards compatible MUST NOT use this argument.
Clients MUST use this information ONLY if an info-token-key with appropriate name is not provided; otherwise, the info-token-value of that token MUST be used instead.
Clients that do not claim being backwards compatible with previous versions of RETS MUST NOT use this argument.


 In chapter 4.8.3 the following should be added:

This argument is deprecated and will be replaced by the Session Information Token (see 4.7.5).
Note that in the OfficeList information token the values are delimitted by commas, rather than semicolons. 
Servers that claim to be backwards compatible with previous versions of RETS MUST still use this argument, but MUST also send the same information in a info-token-key.
Servers that do not claim to be backwards compatible MUST NOT use this argument.
Clients MUST use this information ONLY if an info-token-key with appropriate name is not provided; otherwise, the info-token-value of that token MUST be used instead.
Clients that do not claim being backwards compatible with previous versions of RETS MUST NOT use this argument.




Following text should be inserted before Chapter 4.7.5. Current chapter 4.7.5 should be renumbered.

4.7.5. Session Information Tokens

info-token-key   ::=   Info = info-token-name [ ; info-token-type ] ; info-token-value CRLF
info-token-name   ::= RETSNAME
info-token-type   ::= TOKEN
info-token-value  ::=  TEXT

Information token represents a named and typed piece of information about the current session. This information is sent by the server to the client to use in various occations, eg session and password management, creating search queries targetted to the current user, or in validation expressions (see table 11-34).
Any number of information tokens can be sent in the Login response, provided all of them have unique names.
The info-token-type is one of the DataTypes defined in table 11-9. If info-token-type is missing, the token's data type defaults to Character; the info-token-value MUST NOT include semicolons in this case. Otherwise, the inf-token-type may be any of the DataTypes specified in Table 11-9. The info-token-value must conform to the token's data type.
Names and types of well known tokens are listed in Table 4-1. The server MUST specify tokens shown in bold in that table. These tokens replace the deprecated information described in 4.7.1-4.7.4. The server also MUST specify well-known tokens providing information specified in optional response arguments (see 4.8), if these arguments are used. Clients MUST use the token values rather than the data in the response arguments; however, if the tokens are not present, the response argument values MUST be used.
If a token with a well-known name is specified without the info-token-type, client MUST cast it to the type shown in Table 4-1.

Names and types of well known tokens are listed in Table 4-1.

Table 4-1. Well-Known Information Tokens

Token name

Data type

Deprecated argument

USERID

Character

user-id

USERCLASS

Character

user-class

USERLEVEL

Int

user-level

AGENTCODE

Character

agent-code

BROKERCODE

Character

broker-code

BROKERBRANCH

Character

broker-branch

MEMBERNAME

Character

member-name

MetadataVersion

Character

metadata-version

MetadataTimestamp

DateTime

metadata-timestamp-key

MinMetadataTimestamp

DateTime

min-metadata-timestamp-key

Balance

Decimal

balance

TimeoutSeconds

Int

timeout-key

PasswordExpiration

Date

pwd-expr

WarnPasswordExpirationDays

Int

expr-warn-per

OfficeList

Character

office-list-key
The value of the OfficeList token will be comma-delimited, rather than semicolon-delimited as it was in the case of the OfficeList response argument

More well-known Information Tokens may be added in later version of this document.



Following table should replace Table 11-34. The DataType Column should be used only if the Validation Expressions, as suggested by the Update Workgroup, use data types.

Token Name

Data Type

Description

.TRUE.

BOOLEAN

Boolean value of TRUE (1)

.FALSE.

BOOLEAN

Boolean value of FALSE (0)

.EMPTY.

EMPTY

A value that matches an empty field. Supplies an empty field when used in a SET expression.

.TODAY.

TIME

The current date.

.NOW.

TIME

The current time.

.ENTRY.

type of the current field

The new field value.

.OLDVALUE.

type of the current field

The original value of the field as returned from the host in the search operation. If the field is new, .OLDVALUE. is an EMPTY value.

.USERID.

CHAR

The value of the user-id field returned in the Login transaction, unless an info-token-key named USERID has been returned in the Login transaction.

.USERCLASS.

CHAR

The value of the user-class field returned in the Login transaction, unless an info-token-key named USERCLASS has been returned in the Login transaction.

.USERLEVEL.

CHAR

The value of the user-level field returned in the Login transaction, unless an info-token-key named USERLEVEL has been returned in the Login transaction.

.AGENTCODE.

CHAR

The value of the agent-code field returned in the Login transaction, unless an info-token-key named AGENTCODE has been returned in the Login transaction.

.BROKERCODE.

CHAR

The value of the broker-code field returned in the Login transaction, unless an info-token-key named BROKERCODE has been returned in the Login transaction.

.BROKERBRANCH.

CHAR

The value of the broker-branch field returned in the Login transaction, unless an info-token-key named BROKERBRANCH has been returned in the Login transaction.

.UPDATEACTION.

CHAR

Name of the UpdateAction for which this validation is performed.

.any.

(see Description)

If the name of the SpecValue (stripped of the first and last dot) is equal to a name of one of the info-token-keys returned as part of the Login response, then the type and value of this SpecValue is defined by that info-token-key. If no such info-token-key exists, the value is ERROR.

 

4. Compatibility

While the proposed solution makes the Login response cleaner, better organized and more flexible, it poses a big thread to a backwards compatibility. That's why the deprecated items are left in place, allowing old servers and clients to stay compatible.

In moving forward, both servers and clients are encouraged to break backward compatibility and drop the deprecated items as soon as they believe all the end-points they communicate with have implemented this proposal.

Breaking backwards compatibility will prepare servers and clients to the next stage, where the deprecated items will really be dropped.