Business Practices for Open Access Same-Time Information Systems (oasis) Standards & Communication Protocols Business Practices Requirements




старонка2/11
Дата канвертавання24.04.2016
Памер0.7 Mb.
1   2   3   4   5   6   7   8   9   10   11

002-4.2.3 OASIS Template Constructs
002-4.2.3.1 Template Construction
Standardsection 002-4.3 lists the set of OASIS Templates that shall be supported by all OASIS Nodes. These OASIS Templates are intended to be used precisely as shown for the transfer of data to/from OASIS Nodes, and identify, by Data Elements names, the information to be transferred. The construction of the OASIS Templates shall follow the rules described below:
a. Unique OASIS Template Name: Each type of OASIS Template shall be identified with a unique name which shall be displayed to the User whenever the OASIS Template is accessed.
b. Transfer Protocol: OASIS Templates are transferred using the HTTP protocol. Templates shall support both the "GET" and "POST" methods for transferring "query string" name/value pairs, as well as the OASIS specific "comma separated value" (CSV) format for posting and retrieval of information from OASIS Nodes. HTML screens and forms shall be implemented for each OASIS Template.
c. Source Information: Each OASIS Template shall identify the source of its information by including or linking to the name of the Primary Provider, the Secondary Provider, or the Customer who provided the information.
d. Time Of Last Update: Each OASIS Template shall include a time indicating when it was created or whenever the value of any Data Element was changed.
e. Data Elements: OASIS Templates shall define the elementary Data Element Dictionary names for the data values to be transferred or displayed for that Template.
f. Documentation: OASIS Information shall be in non-cryptic English, with all mnemonics defined in the Data Element Dictionary or a glossary of terms. TSIPs shall provide on-line descriptions and help screens to assist Users understanding the displayed information. Documentation of all formats, contents, and mnemonics shall be available both as displays and as files that can be downloaded electronically. In order to meet the "User-Friendly" goal and permit the flexibility of the OASIS Nodes to expand to meet new requirements, the OASIS Templates shall be as self-descriptive as possible.
002-4.2.3.2 Template Categories
OASIS Templates are grouped into the following two major categories:
a. Query/Response: These Templates are used to query and display information posted on an OASIS Node. Each query/response Template accepts a set of user specified Query Variables and returns the appropriate information from data posted on the OASIS Node based on those Query Variables. The valid Query Variables and information to be returned in response are identified by Data Element in Section 4.3.
b. Input/Response: These Templates are used to upload/input information on an OASIS Node. The required input information and information to be returned in response are identified by Data Element in Section 4.3, Template Descriptions.
002-4.2.3.3 Template HTML Screens
Though the exact form and content of the HTML screens and forms associated with the OASIS Templates are not dictated by this document, the following guidelines shall be adhered to for all HTML screens and forms implemented on an OASIS Node:
a. Data Element Headings: Data displayed in an HTML screen/form shall be labeled such that the associated data value(s) is(are) easily and readily identifiable as being associated with a particular OASIS Template Data Element. HTML "Hot-Links" or other pointer mechanisms may be provided for Data Element headings in OASIS Templates which permit the User to access documentation describing the meaning, type, and format of the associated data.
b. Display Limitations: HTML screens and forms shall be implemented in such a way to allow the display of all data specified for each OASIS Template. This may take the form of "wrapping" of lines of information on the screen, the use of horizontal and/or vertical scrolling, or the use of "Hot-Links" or other pointer mechanisms. There is not necessarily a one-to-one relationship between HTML screens implemented on OASIS Nodes, and their associated Template. However, all Template Data Elements shall be viewable through one or more HTML screens.
c. Template Navigation: HTML "Hot-Links" or other pointer mechanisms may be provided to assist the navigation between screens/forms associated with related OASIS Templates.
002-4.2.4 Query/Response Template Requirements
Retrieval of information posted on an OASIS Node is supported by the Query/Response Templates. The "query" identifies the OASIS Template and optionally supplies additional Data Elements that may be used to select specific information to be returned in the "response".
002-4.2.4.1 Query Requirements
Query information is transferred to an OASIS Node using the HTTP protocol as a string of Query Variables in the form of name/value pairs. Query Variable name/value pairs are specified as a collection of encoded strings (e.g., blank characters replaced by plus (+) character, etc.) in the form of name=value, with each name/value pair separated by ampersands (&) (see section 4.2.6). OASIS Nodes shall support the following methods for Users to input Query information:
a. HTML: HTML FORM input and/or hypertext links shall be provided to allow Users to specify OASIS Template Query Variables. This will be the easiest way to obtain information and should be the choice of most casual Users and for simple requests. The exact nature and form of these HTML screens are not specified, and may differ between OASIS Nodes.
b. GET Method: The HTTP GET method for specifying query information appended to a standard OASIS URL shall be supported. Using this method, the name=value formatted Query Variables preceded by a question mark (?) are appended to the URL. Each "name" in a name/value pair corresponds to a Data Element name associated with that Template. OASIS Nodes shall support the specification of all Data Elements associated with a Template by both their full name and alias as defined in the Data Dictionary. The "value" in a name/value pair represents the value to be associated with the Data Element being specified in the appropriate format as defined in the Data Dictionary and encoded according to the HTTP protocol.
c. POST Method: The HTTP POST method for specifying query information in the message body shall be supported. Using this method, the name=value formatted Query Variables shall be transferred to an OASIS Node using the "Content-length:" HTTP header to define the length in bytes of the encoded query string and the "Content-type: application/x-www-form-urlencoded" HTTP header to identify the data type included in the message body. Each "name" in a name/value pair corresponds to a Data Element name associated with that Template. An OASIS Node shall support the specification of all Data Elements associated with a Template by both their full name and alias as defined in the Data Dictionary. The "value" in a name/value pair represents the value to be associated with the Data Element being specified in the appropriate format as defined in the Data Dictionary and encoded according to the HTTP protocol.
User queries using any of the above methods are supported directly by the User's web browser software. More sophisticated data transfer mechanisms, such as the automated querying of information based on Query Variable strings contained in a User data file (i.e., "uploading a file containing a URL string), require appropriate software (e.g., "fetch_http") running on the User's computer system to effect the data transfer.
002-4.2.4.2 Response Requirements
In response to a validly formatted Query for each Query/Response OASIS Template, the OASIS Node shall return the requested information in one of two forms based on the User specified OUTPUT_FORMAT Query Variable:
a. HTML: If the User requests the response to have the format of "HTML" (OUTPUT_FORMAT=HTML) then the response from the OASIS Node shall be a web page using the HTML format. This shall be the default for all Query/Response Templates.
b. CSV Format: Comma Separated Value (CSV) format (OUTPUT_FORMAT=DATA) returns the requested information in the body of the HTTP response message. The "Content-length:" HTTP header shall define the length in bytes of the response, and the "Content-type: text/x-oasis-csv" HTTP header shall be used to identify the data type included in the message body (see CSV File Format).
002-4.2.5 Input/Response Template Requirements
Input/Response Templates support the posting of information on an OASIS Node, including reservations for transmission/ancillary service and services for sale on the secondary market, etc. The "input" identifies the required data associated with an OASIS Template to be posted on the OASIS Node, and the "response" specifies the information returned to the User.
002-4.2.5.1 Input Requirements
Input information is transferred to an OASIS Node using the HTTP protocol as either a string of Query Variables in the form of name/value pairs, or as a Comma Separated Value (CSV) message. Query Variable name/value pairs are specified as a collection of encoded strings (e.g., blank characters replaced by plus (+) character, etc.) in the form of name=value, with each name/value pair separated by ampersands (&). CSV formatted messages are specified in the body of an HTTP message as a series of Data Records preceded by a fixed set of header records (see section 4.2.7). OASIS Nodes shall support the following methods for Users to transfer Input data:
a. HTML: HTML FORM input shall be provided to allow Users to specify the necessary Input data associated with each Input/Response OASIS Template. This may be in the form of fill in blanks, buttons, pull-down selections, etc., and may use either the GET or POST methods. The exact nature and form of these HTML screens are not specified, and may differ between OASIS Nodes.
b. GET Method: The HTTP GET method for specifying Input information in the form of a query string appended to a standard OASIS URL shall be supported. Using this method, the name=value formatted Query Variables preceded by a question mark (?) are appended to the URL. Each "name" in a name/value pair corresponds to a Data Element name associated with that Template. OASIS Nodes shall support the specification of all Data Elements associated with a Template by both their full name and alias as defined in the Data Dictionary. The "value" in a name/value pair represents the value to be associated with the Data Element being specified in the appropriate format as defined in the Data Dictionary and encoded according to the HTTP protocol.
c. POST Method: The HTTP POST method for specifying Input information in the form of a query string in the message body shall be supported. Using this method, the name=value formatted Query Variables shall be transferred to an OASIS Node using the "Content-length:" HTTP header to define the length in bytes of the encoded query string and the "Content-type: application/x-www-form-urlencoded" HTTP header to identify the data type included in the message body. Each "name" in a name/value pair corresponds to a Data Element name associated with that Template. OASIS Nodes shall support the specification of all Data Elements associated with a Template by both their full name and alias as defined in the Data Dictionary. The "value" in a name/value pair represents the value to be associated with the Data Element being specified in the appropriate format as defined in the Data Dictionary and encoded according to the HTTP protocol.
d. CSV Format: Comma Separated Value (CSV) formatted Input information transferred in the body of a User's HTTP message shall be supported. The "Content-length:" HTTP header shall define the length in bytes of the Input, and the "Content-type: text/x-oasis-csv" HTTP header shall be used to identify the data type included in the message body.
002-4.2.5.2 Response to Input
In response to a validly formatted Input for each Input/Response OASIS Template, the OASIS Node shall return an indication as to the success/failure of the requested action. The OASIS Node shall respond to the Input in one of two forms, based on the OUTPUT_FORMAT, which was input by a User either as a Query Variable or in a CSV format Header Record:
a. HTML: If the User requests the response to have the format of "HTML" (OUTPUT_FORMAT =HTML) then the response from the OASIS Node shall be a web page using the HTML format. This shall be the default for all Input/Response Templates invoked using either the FORM, GET or POST methods of input.
b. CSV Format: Comma Separated Value (CSV) format (OUTPUT_FORMAT=DATA) returns the response information in the body of the HTTP response message. The "Content-length:" HTTP header shall define the length in bytes of the response, and the "Content-type: text/xoasis- csv" HTTP header shall be used to identify the data type included in the message body. This shall be the default for all Input/Response Templates invoked using the CSV Format methods of input.
002-4.2.6 Query Variables
002-4.2.6.1 General
Both Query/Response and Input/Response OASIS Templates shall support the specification of a query string consisting of Query Variables formatted as name/value pairs. OASIS Nodes shall support the specification of Data Element names ("name" portion of name=value pair) in both the full name and alias forms defined in the Data Dictionary. OASIS Nodes shall support the specification of Query Variables from the User using either the HTTP GET or POST methods. On input, Data Element names and associated values shall be accepted and processed without regard to case. On output, Data Element names and associated values may not necessarily retain the input case, and could be returned in either upper or lower case.
002-4.2.6.2 Standard Header Query Variables
The following standard Query Variable Data Elements shall be supported for all OASIS Templates and must be entered for each Query by a User:
VERSION

TEMPLATE


OUTPUT_FORMAT

PRIMARY_PROVIDER_CODE

PRIMARY_PROVIDER_DUNS

RETURN_TZ


Since these header Query Variables must be supported for all Templates, they are not listed explicitly in the Template descriptions in Section 4.3 The User must enter all standard Header Query Variables with appropriate values.
002-4.2.6.3 Responses to Queries
Responses to Queries will include the following information as a minimum:
TIME_STAMP

VERSION


TEMPLATE

OUTPUT_FORMAT

PRIMARY_PROVIDER_CODE

PRIMARY_PROVIDER_DUNS



RETURN_TZ
The additional information shall include:
a. The requested information as defined by the Template indicated in the Query
b. For CSV downloads, the additional header Data Elements required (see section 4.2.7.3)
002-4.2.6.4 Multiple Instances
Certain Query Variables may be repeated in a given Query/Response OASIS Template query string. Such multiple instances are documented in the Template definitions using an asterisk (*) after the Query Variable. When more than one instance of the Query Variable is specified in the query string, OASIS Nodes shall recognize such multiple instances by either the Data Element's full name or alias suffixed with sequential numeric qualifiers starting with the number 1, (e.g., PATH_NAME1=abc&PATH_NAME2=xyz, or PATH1=abc&PATH2=xyz). At least 4 multiple instances will be permitted for each Query Variable marked with an asterisk (*).
002-4.2.6.5 Logical Operations
OASIS Nodes shall use the following logical operations when processing Query Variables for Query/Response OASIS Templates.
a. All Query Variables, with the exception of multiple instances of the same Query Variable Data Element, shall be operated on to return information based on the logical- AND of those Query Variables. For example, the query string "SELLER_CODE=abc &PATH=xyz" should return information associated with only those records that are on transmission path "xyz" AND associated with transmission provider "abc."
b. Multiple instances of the same Query Variable shall be operated on as logical-OR. For example, "SELLER_CODE=abc &PATH1=xyz&PATH2=opq" should return information associated with transmission provider "abc" AND either transmission path "xyz" OR transmission path "opq". Some logical operations may exclude all possibilities, such that the responses may not contain any data.
002-4.2.6.6 Handling of Time Data Elements
a. In cases where a single Query Variable is provided to select information associated with a single Template Data Element that represents a point in time (e.g., TIME_OF_LAST_UPDATE), OASIS Nodes shall return to the User all requested information whose associat Data Element time value (e.g. TIME_OF_LAST_UPDATE) is equal to or later than the value specified by the Query Variable. In this case the stop time is implicitly "now".
b. A pair of Query Variables (e.g. START_TIME_QUEUED and STOP_TIME_QUEUED) that represents the start and stop of a time interval but is associated with one single Template Data Element (e.g. TIME_QUEUED) shall be handled by OASIS Nodes to return to the User all requested information whose associated Data Element time value falls within the specified time interval.
c. A pair of Query Variables (e.g. START_TIME and STOP_TIME Query Variables) that represents the start and stop of one time interval but is associated with another pair of Template Data Elements (e.g. START_TIME and STOP_TIME of a service offering) that represents a second time interval, shall be handled by OASIS Nodes to return to the User all requested information whose associated Data Element time interval overlaps any portion of the specified time interval. Specifically, the START_TIME Query Variable selects all information whose STOP_TIME Data Element value is later than the START_TIME Query Variable, and the STOP_TIME Query Variable selects all information whose START_TIME Data Element value is earlier than the STOP_TIME Query Variable. For example:

The transoffering Template query string "START_TIME 970101000000ES&STOP_TIME 970201000000ES" shall select from the OASIS database all associated offerings whose start/stop times overlap any portion of the time from 00:00 January 1, 1997, to 00:00 February 1, 1997. This would include offerings that (1) started prior to Jan. 1 and stopped any time on or after Jan. 1, and (2) started on or after Jan 1 but before Feb 1


d. For changes to and from daylight savings time, either Universal Time or the correct time and zone must be used, based on whether daylight savings time is in effect.
e. All time values shall be checked upon input to ensure their validity with respect to date, time, time zone, and daylight savings time.
002-4.2.6.7 Default Values
Query Variables that are not specified by the User may take on default values as appropriate for that Query Variable at the discretion of the OASIS TSIP.
002-4.2.6.8 Limitations on Queries
OASIS TSIP may establish validation procedures and/or default values for Query Variables to restrict the size and/or performance impact of overly broad queries.
002-4.2.7 CSV Format
002-4.2.7.1 General Record Format
OASIS Users shall be able to upload information associated with Input/Response OASIS Templates and download information associated with all OASIS Templates using a standardized Comma Separated Value (CSV) format. CSV formatted data is transferred to/from OASIS Nodes as part of the body of an HTTP message using the "Content-length:" HTTP header to define the length in bytes of the message body, and the "Content-type: text/x-oasis-csv" HTTP header to identify the data type associated with the message body. CSV formatted data consists of a fixed set of header records followed by a variable number of Data Records. Each record shall be separated by a carriage return plus line feed (denoted by the symbol  in all examples). The fields within a record shall be delimited by commas (,). All data within a CSV formatted message shall use printable ASCII characters with no other special embedded codes, with the exception of the special encoding requirements associated with text fields.
002-4.2.7.2 Input Header Records
The following standard header records are required for the uploading of Input data for all Input/Response OASIS Templates:
VERSION=nn.n

TEMPLATE=aaaaaaaaaa

OUTPUT_FORMAT=[DATA] 

PRIMARY_PROVIDER_CODE=aaaa

PRIMARY_PROVIDER_DUNS=nnnnnnnnn

RETURN_TZ=aa

DATA_ROWS=nnn

COLUMN_HEADERS=[Template Data Element names separated by commas] 

The format of the value associated with each of the Input header record Data Elements are dictated by the Data Dictionary. The value associated with the DATA_ROWS Data Element shall define the total number of Data Records that follow in the message after the COLUMN_HEADERS record. The COLUMN_HEADERS record defines, by Data Element name, the data associated with each comma separated column contained in each subsequent Data Record (row). On Input, either the Data Element's full name or alias listed in the Data Dictionary may be specified.
002-4.2.7.3 Response Header Records
When explicitly specified using the OUTPUT_FORMAT=DATA Query Variable or implied by the Input of a CSV format message, the OASIS Nodes shall respond with the following standard response header records for all OASIS Templates:
REQUEST_STATUS=nnn

ERROR_MESSAGE=aaa

TIME_STAMP=yyyymmddhhmmsstz

VERSION=nn.n

TEMPLATE=aaaaaaaaaa

OUTPUT_FORMAT=DATA

PRIMARY_PROVIDER_CODE=aaaa

PRIMARY_PROVIDER_DUNS=nnnnnnnnn

RETURN_TZ=tz

DATA_ROWS=nnn

COLUMN_HEADERS=[Template Data Element names separated by commas] 

The format of the value associated with each of the Response header record Data Elements are dictated by the Data Dictionary. The value associated with the DATA_ROWS Data Element shall define the total number of Data Records returned in the message following the COLUMN_HEADERS header record. The COLUMN_HEADERS record defines, by Data Element name, the data associated with each comma-separated column contained in each subsequent Data Record (row). In all OASIS Node responses, the Data Element's full name shall be listed in the COLUMN_HEADERS record. The order of the column headings shall be the same as shown in the Templates for URL uploads and downloads. For graphical displays, the Provider may define the order that the Data Element names are shown.


002-4.2.7.4 Data Records
Data Records immediately follow the standard Input or Response header records. With the exception of Data Records grouped together as a single "logical record" through the use of Continuation Records, each Data Record in a CSV formatted Input message represents a single, complete execution of the associated OASIS Template. That is, sending five CSV formatted Input messages for a given Template to the same PRIMARY_PROVIDER_CODE with a single Data Record per message shall be handled in exactly the same fashion as sending a single CSV formatted Input message for the same Template and PRIMARY_PROVIDER_CODE which contains five Data Records. Each field (column) within each Data Record defines the value to be associated with the corresponding Data Element defined in the COLUMN_HEADERS record. The number of Data Records in the message is defined by the DATA_ROWS header record. The data values associated with each column Data Element are interpreted based on the Data Element type as defined in the Data Dictionary:
a. Numeric Data Elements: All numeric Data Elements shall be represented by an ASCII string of numeric digits in base ten, plus the decimal point.
b. Text Data Elements: Alphabetic and alphanumeric Data Elements shall be represented as ASCII strings and encoded using the following rules:


  • Text strings that do not contain commas (,) or double quotes (") shall be accepted both with and without being enclosed by double quotes.

  • Text fields with commas (,) or double quotes (") must be enclosed with double quotes. In addition double quotes within a text field shall be indicated by two double quotes ("").

  • The Data Element field length specified in Data Dictionary does not include the additional double quotes necessary to encode text data.

c. Null Data Elements: Null Data Elements shall be represented by two consecutive commas (,,) corresponding to the leading and trailing (if appropriate) Data Element comma separators. Null text strings may optionally be represented by two consecutive double quote characters within the leading and trailing comma separators (i.e., Y,"",Y).

1   2   3   4   5   6   7   8   9   10   11


База данных защищена авторским правом ©shkola.of.by 2016
звярнуцца да адміністрацыі

    Галоўная старонка