UserRoles Techincal Documentation External V1.0

8/10/2019 UserRoles Techincal Documentation External V1.0

1/32

User Roles Web Services Web Services technical Guide 29

User Roles Web

Services Technical

Documentation

User Roles Web Services

Guide For External Users

June 10th, 2008

Version 1.0


2/32

Reference

Prepared for

User Roles External Web Services Clients

Prepared by

Sabre Inc.

Date

March 01st , 2008

2008, Sabre Inc. All rights reserved.

This documentation is the confidential and proprietary intellectual

property of Sabre Inc. Any unauthorized use, reproduction,

preparation of derivative works, performance, or display of this

document, or software represented by this document, without the

express written permission of Sabre Inc. is strictly prohibited.

Sabre, the Sabre logo design, and Product Name are trademarks

and/or service marks of an affiliate of Sabre Inc. All other

trademarks, service marks, and trade names are owned by their

respective companies.


3/32

User Roles Web Services Web Services technical Guide 29


4/32

ii User RolesWeb Services Web Services Technical Users Guide June 10, 2009

User RolesTechnical User Guide

D O C U M E N T R E V I S I O N I N F O R M A T I O N

The following information is to be included with all versions of the document.

Project Name User Roles Web Services Project Number

Prepared by Ramesh Kumar Pitani Date Prepared

Revised by Date Revised

Revision Reason Revision Control No.












5/32

Sabre Inc.Confidential/All Rights Reserved Table of Contents iii


6/32

iv User RolesWeb Services Web Services Technical Users Guide June 10, 2009

Table of Contents

1111 I n t r o d u c t i on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1 About This Guide ....................................................................................................................... 1

1.2 Standards and Specifications ................................................................................................... 1

2 A c c e s s i n g U s e r R o l e s W e b S e r v i c e s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.1 About User Roles Web Services ............................................................................................... 3

2.2 Types of Web Services .............................................................................................................. 4

2.2.1 Session management Services ......................................................................................... 4

2.2.2 User Roles Services .......................................................................................................... 4

2.3 Message Structure..................................................................................................................... 6

2.4 Requesting Payload Content ..................................................................................................... 7

2.5 Security ...................................................................................................................................... 7

2.5.1 Line Security ...................................................................................................................... 7

2.5.2 Authentication .................................................................................................................... 8

2.5.3 Authorization ...................................................................................................................... 8

2.5.4 Confidentiality .................................................................................................................... 8

2.6 Network Connectivity ................................................................................................................ 8

2.7 Web Services Sessions .............................................................................................................. 9

2.7.1 SessionCreateRQ Request XML Example ....................................................................... 10

2.7.2 User Roles Service Requests Using A Session .............................................................. 12

2.7.3 Ending the Session ........................................................................................................... 13

2.8 Web Services Error Handling .................................................................................................. 14

3 R o l e S e r v i c e s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 7

3.1 User Roles Data Overview....................................................................................................... 17

3.2 Creating Role .......................................................................................................................... 20

4.2.1 How To Create a Role with Permissions......................................................................... 20

4.2.2 Sample XML Create Role with Permissions Request ..................................................... 20

4.2.3 Sample XML Create Role with Permissions Successful Response ............................... 42

4.2.4 Sample XML Create Role with Permissions Error Response ......................................... 43

3.3 Retrieving Role......................................................................................................................... 44

4.3.1 Sample XML Retrieve Role Successful Response .......................................................... 45

4.3.2 Sample XML Retrieve Role Error Response .................................................................... 47

3.4 Updating Role........................................................................................................................... 47

4.4.1 How To Fully Update a Role ............................................................................................ 49

4.4.2 Sample XML Update Role Successful Response ............................................................ 52

4.4.3 Sample XML Update Role Error Response ...................................................................... 53


7/32

Sabre Inc.Confidential/All Rights Reserved Table of Contents v

3.5 Searching For Role .................................................................................................................. 54

4.5.1 Sample XML Role Search Request .................................................................................. 55

4.5.2 Sample XML Role Search Response ............................................................................... 57

4.5.8 Sample XML No Results Response Message ................................................................. 61

4.5.8 Sample XML Role Search Error Response ...................................................................... 61

3.6 Deleting Role ............................................................................................................................ 61

4.6.1 Sample XML Role For Delete Request ............................................................................ 62

4.6.2 Sample XML Role Delete Successful Response ............................................................. 62

4.6.3 Sample XML Role Delete Error Response ....................................................................... 63


8/32


9/32

Sabre Inc.Confidential/All Rights Reserved Introduction 1

1.1 Abo ut Th is Gu i de

This guide is for architects and developers to learn how to compose XML formatted requests and

responses to consume User Roles Web Services.

The information in this guide is intended to help architects and developers accomplish the following:

Incorporate into a client program the composition of the XML request and response formats to

acquire appropriate Sabre Integrated Computing Environment (ICE) authentication and

authorization security credentials represented by a unique token found in the response.

Incorporate into a client program the composition of the XML to include the unique tokenized

ICE security credential in subsequent User Roles Web Service requests.

Consume User Roles Web Services by learning the different request types, their corresponding

responses and the different protocols and standards involved.

1.2 S ta n d a rd s a n d S p e c i f i c a t i o n s

The following specifications gives the format of roles data, the packaging format of the messages,

and the transport mechanisms.

HTTP 1.1 [RFC2616] used for transport protocol

MIME specifications [RFC2045], [RFC2046], and [RFC2387] used for the SOAP message

headers and instructions

SOAP 1.1, Electronic Business using XML [ebXML], and W3C XML standards used to define

and describe the SOAP messages

SOAP Messages with Attachments specification [SOAPAttach] used for the ebXML messages

that include header and payload containers

WS-Security standards partially adopted for some security elements in the SOAP header

W3C XML 1.0 used for both Sabre XML message specifications and Sabre XML messages put

into the payload container of the SOAP message.

OpenTravel Alliance specification (http://www.opentravel.org) - used as the basis for the profile

request and response XML payloads.

SOAP Simple Object Access Protocol

Character Specifications

1 Introduction 1


10/32

A-2 IntroductionTechnical Reference Guide TemplateWriter Guide 07/29/08 Revision: UserRoles Techincal Documentation_External_V1.0.doc

o ISO 10646/Unicode, Basic Latin and Latin 1 Supplement

o UCS Transformation Format 8 (UTF-8 Encoding)

o ISO 8859 Latin 1 Character Set

o Sabre Character Set


11/32


12/32

4 OTA Profile Services OTA Profile Services Guidelines June 10, 2009

Cert/CAT:

Certification testing for internal Sabre clients and CAT testing for Sabre customers use the following

URL. The actual URL will be provided at the time of testing.

https://cert.webservices.sabre.com/tsts

Production:

There is a single URL for production web service acccss.

https://webservices.sabre.com/websvc

The network protocol used to communicate is HTTPS/SOAP.

SOAP is the message protocol that encodes Web services messages before they are sent. Clientapplications, then, consume all User Roles Web Services with XML/SOAP or WSDL/SOAP.

2.2 Typ es o f Web Se rv ice s

When you provide a web client that consumes User Roles Web Services, you use two basic types of

messages: session management messages and the User Roles Service request messages.

2.2.1 Se s s i o n ma n a g e me n t Se r v i c e s

Web Services messages have been created to open and close sessions. Session services do not request

content from User Roles, and they do not contain business logic. Session services allow for greater

efficiency when processing client requests because time consuming security data retrieval overhead

is avoided by maintaining that data in the session and representing the session by a security token

returned to the client.

The SessionCreateRQ request contains a client composed unique conversation ID and a Sabre

supplied security credential to initiate a connection, a session, authentication and authorization to

access particular Sabre services such as the User Roles Web Services.

The SessionCreateRS response returns to the web client the unique conversation ID and a unique

security token for use in subsequent User roles profile related requests. The session lasts either until

the client sends a SessionCloseRQ request or the session time out is exceeded.

The establishment of the session for User roles services includes granting access only to the owner

of the profiles stored by Sabre. This limited access is accomplished by the security configuration

represented by the security credentials presented by the web client in the SessionCreateRQ.

2.2.2 Us er Ro le s Se rv ic es

User Roles web clients can request via the internet the following profile services:

Role Create the web client sends Role+Permissions data to Sabre to add to the roles data stored

by Sabre. The client sends the Sabre_RolesCreateRQ XML request message and gets the


13/32

Sabre Inc.Confidential/All Rights Reserved Message Structure 5

Sabre_RoleCreateRS XML response message back indicating success or failure and some role-

related information.

Role Update the web client sends updated Permissions data to Sabre to modify Permissions

associated with Role. The client sends the Sabre_RolesUpdateRQ XML request message and

gets the Sabre_RolesUpdateRS XML message response indicating success or failure.

The Sabre_RolesUpdateRQ XML request perform full update of Permissions Data.

Role Read the web client sends a request to retrieve a Permissions data using the

Sabre_RolesReadRQ XML request message and gets the Permissions data stored by Sabre is

returned in the Sabre_RolesReadRS XML response message.

Role Search the web client sends search criteria for a role contained in the

Sabre_RolesSearchRQ XML request message and response is returned to the web client in the

Sabre_RolesSearchRS XML response message.

Profile Delete the web client sends a request to delete existing Role+Permissions data for

delete in the Sabre_OTA_ProfileDeleteRQ XML request message.

2.3 M ess age St r uc t u re

The messages for the User Roles Web Services conform to the following two specifications:

The ebXML part of the SOAP envelope conforms to SOAP with Attachments

The content of the payload attachments conforms to User Roles XMLwhich is based on but not100% compatible with the published OTA profile related schemas.

The structure of the messages is based on Internet standards such as HTTP, HTTPS, and the MIME

mail extensions. HTTPS is the communications protocol.

The SOAP with Attachments protocol is a MIME multipart message with the following MIME parts:

The header container This is a SOAP envelope, which is an XML document.

The payload container This is the application payload, and it is formatted as User RolesXML.

The SOAP with Attachments protocol is used to format the messages for Java clients, and the

payload is sent as an attachment. Instead of sending the payload as an attachment, however, it can be

included inside the SOAP wrapper. Java Axis clients include the payload inside the SOAP wrapper.

If WSDL and Microsoft .NET Framework are used to format messages, the payload is included

inside the SOAP wrapper.


14/32


2.4 R e q u e s t i n g P a y l o a d C o n t e n t

Payload content is requested by including the action code that corresponds to the service being

called.

A unique action code identifies the request and response payloads for every one of the User Roles

Web Services.

The action codes, represented by the eb:Action element in the SOAP header, are the following:

Service Name Action code

Role Create Roles_EXT_CreateRQ

Role Read Roles_EXT_ReadRQ

Role Search Roles_EXT_SearchRQ

Role Update Roles_EXT_UpdateRQ

Role Delete Roles_EXT_DeleteRQ

2.5 Security

Sabre Web Services have implemented multiple layers of security for client applications. These

layers include line security, authentication, authorization, and confidentiality.

2.5.1 L i ne Se cu r i ty

Line security is the layer that secures the data traveling on the line over the Internet between external

systems, Sabre data centers and responses back to the external systems. User Roles Web Services

support point-to-point synchronous transport HTTPS using SSL with 128-bit encryption.

Clients that consume Sabre Web Services must implement line security with a secure sockets layer,

and they must secure the envelopes and payloads with HTTPS.

2 .5 .2 Authent icat ion

Authentication is the layer that allows web client access to the User Roles Web Services. Security

credentials are found in the wsse:Username, wsse:Password, Organization, and Domain


15/32


16/32


2.7 Web Ser v i ces Ses s i ons

A Web Services session is created when a correctly formatted SessionCreateRQ request is sent to the

Sabre Web Services infrastructure, and a binary security token is returned in the SessionCreateRS

message.

An exchange of messages between a web client and a business application, such as one of the User

Roles web services, follows. A unique conversation ID and binary security token identify the session

and are used together throughout the duration of the session.

A simplified flow of a Web Services session is as follows:

1. The client opens a Web Services session by sending the SessionCreateRQ Service request. This is

the only request message that includes the client security credentials provided by Sabre.Security credentials in the SessionCreateRQ message consist of the wsse:Username,

wsse:Password, Organization, and Domain elements. In addition to these credentials, the

client generates a unique conversation ID. Often the conversation ID achieves uniqueness by

including a timestamp and the URL of the client web site as part of the conversation ID.

2. The Sabre Web Services infrastructure receives this request, authenticates the securitycredentials, processes it, and returns a security token with the SessionCreateRS message. The

SWS infrastructure also returns the same conversation ID sent. The web client stores the session

data represented as a conversation ID and security token, and includes them with each

subsequent SOAP request until the conversation is closed. This avoids the overhead of re-

authentication that would occur if this process needed to happen for every type of User Roles

service request.

3. The web client and the Sabre User Roles servicesexchange messages that represent a businessworkflow.

4. When the SWSsession is no longer needed, the client closes the session by sending theSessionCloseRQ Service request with the same unique conversation ID and security token of the

session it is closing.

In a given Web Services session, all request messages include the same unique conversation ID and

binary security token. Only one conversation ID must exist per business process work flow. Once

again, often the URL of the web client web site plus a timestamp is used for the conversation ID.

If activity has not occurred within the session time out limit, in the order of 20 minutes, the businessprocess flow represented by the session is not guaranteed to be alive.


17/32

Sabre Inc.Confidential/All Rights Reserved Web Services Sessions 9

2.7.1 S e s s i o n C r e a t e R Q R e q u e s t X M L E x a m p l e

The web client establishes an SWS session by sending security credentials and a unique conversation

ID as shown in the following example:

The envelope

999999

123123

2007-12-15T11:15:[email protected]

999999992007-12-15T11:15:12Z2007-12-15T11:15:12Z

SabreSuppliedUserNameSabreSuppliedPasswordSabreSuppliedOrganizationSabreSuppliedDomain/Domain>

The SOAP payload


18/32


A typical response is:

SOAP envelope -

123123

999999 SabreSuppliedPseudoCity2007-12-15T11:15:[email protected]

97d9da35-3a36-4092-a934-99ba554ac712@732006-12-28T18:34:1699999999

Shared/IDL:IceSess\/SessMgr:1\.0.IDL/Common/!ICESMS\/STSB!ICESMSLB\/STS.LB!-4617338326250370976!113241!0

Session Create Response Message

SOAP payload -



19/32

Sabre Inc.Confidential/All Rights Reserved Web Services Sessions 11

2.7.2 U s e r R o l e s S e r v i c e R e q u e s t s U s i n g A S e s s i o n

The web client request SessionCreateRQ establishes a session with the Sabre Web Services

Gateway. The SessionCreateRS message returns to the web client a security token as described in

the previous paragraph.

The web client uses this token along with other data like the ConversationId associated with

session to compose subsequent User Roles service requests as follows:



20/32


SWS uses the security token to authenticate and authorize the profile create request message without

the overhead required to retrieve user security credentials from the Sabre security data store.

2.7.3 En d i ng th e Se ss io n

Once the web client establishes a SWS session one or more profile requests are made by the user.

For example an airline agent may need to retrieve several customer profiles and update those profiles

all in a session. The SWS session ends in one of two ways. Either the user sends the

SessionCloseRQ message populated with the session data or the SWS infrastructure ends the

session when the session timeout has occurred..

NOTE: If the web client user intends to send only a single profile service request, the

SessionCreateRQ and SessionCloseRQ messages must still sandwich the single request.

The SessionCloseRQ message for the example follows:


clientURL

webservices.sabre.com

IPCC

Session

SessionCloseRQ

mid:20001209-133003-2333@clientURL

2004-02-15T11:15:12Z

2004-02-15T11:15:12Z

Shared/IDL:IceSess\/SessMgr:1\.0.IDL/Common/!ICESMS\/STSB!ICESMSLB\/STS.LB!-4617338326250370976!113241!0


21/32

Sabre Inc.Confidential/All Rights Reserved Web Services Error Handling 13

NOTE: The following is the second multipart MIME part containing the Sabre XML message:\


2.8 W e b S e rv i c e s E r r o r H a n d l i n g

Several error categories are possible.

Sabre Web Services errors These type of errors occur within the Sabre Web Servicesinfrastructure, and they are caused by faulty messages from the web client or problems with the

User Roles Web Services. The infrastructure detects and generates these errors, and returns themas SOAP faults, with or without ebXML headers.

Business application errors These errors are generated by the business application services thatare called by the SWS infrastructure. The web client request, the network routing between the

SWS infrastructure and the business application service,or the business application service cause

these types of errors. They are returned to clients in the ErrorRS XML response format.

System errors generated by web clients These are caused by the web clients themselves and areexternal to the User Roles Web Services. They normally occur in the development environment,

and are returned to the client.

When the response contains the element, an HTTP status code of 500 is

returned. If no SOAP fault exists, HTTP Status Code 200 is returned. Other codes depend on the

request and are shown later in the document.

1. Have Sabre review the set of composed XML messages.

2. Setup with Sabre for CAT testing.


22/32


3.1 U s e r R o l e s D a ta O v e rv i e w

User Roles contains 2 main data sections. These sections are: Role Identity Data and Permissions

Data.

Role Identity data has a base element < RolesIdentity> which consists of the following attributes:

Role Name

Domain ID

Role Status Code

Permissions data has a base element < AssociatedPermissions> which consists of the following

attributes:

o Permission Code

o Application Code

3 User Roles 3


23/32

Sabre Inc.Confidential/All Rights Reserved User Roles 15

3.2 C re at in g Ro le

Web clients create a role over the web interface using the Sabre_RolesCreateRQ request.

Also refer to the SampleRoleCreateRQ.xml for an exhaustive payload containing every possible data

element and attribute all annotated to explain data restrictions, whether optional or required data, and

other due explanations.

The following sections describe the most typical subset of data currently in use.

3.2.1 H o w T o C r e a t e a R o l e w i t h P e r m i s s i o n C o d e s

Assume the SessionCreateRQ has already returned the binary session token and conversation ID forthe web client session being described.

The Role data sent from the web client is usually a small subset of all possible data. The first task

then is to determine what the subset is that represents the traveler data for this web client.

The following section shows a typical traveler profile.

3.2.2 Sa m p le XML Cr e a t e Ro le Re q u e s t

The Create Traveler XML request begins with the following boilerplate:

Right after this section comes base element . There are no attributes in element.

Now define the unique identification for this role. This is element.

The following attributes: RoleName, RoleStatusCode and DomainID are required. RoleName is

unique. This unique name identifies all permission codes associated to this role. Role Name mapped

to RL_NM column in RL_PTY table. If Role name is already exist in this table table, then response

should have error message stating that Role name already exist. DomainID can be set to any of the

up-to-20-characters-long values. DOMN_ID column in RL_PTY represents Domain ID value. This

value can be anything length up to 20. RoleStatusCode is can be one these values AC(Active),

DL(Deleted) and IN(Inactive). OP_STS_CD represents Role Status Code in RL_PTY table.

If value of any of the mandatory attributes is set to the empty string or it is not set at all, user will get

an appropriate error message.


24/32


The Permissions section section looks as follows. element can hold maximum 50

PermissionCode value should be one of the value defined in C_PERMSN table. If Permission code

does not exist in this table, then response should give error message stating that Permission Code

does not exist. ApplicationCode value should be one of the value defined in EC_RL_APPL table. If

PermissionCode/Application code does not match, then response shows corresponding message. All

Permission Codes related to Role appear in RL_PTY_PERMSN table with RL_ID come from

RL_PTY table.

Note: Role can be created in AC or IN status, not DL status.

3.2.3 S a m p l e X M L C r e a t e R o l e S u c c e s s f u l R e s p o n s e

When role is successfully created, the following response message is returned:

3.2.4 S a m p l e X M L C r e a t e R o l e E r r o r R e s p o n s e

When role for some reason could not be created, an error message is returned. Each error message

contains Errors section with short description of a problem which was encountered during profile

creation. For User Roles, Role Create Service each Error message is prefixed with C:::. The sample

error message has been placed below:

C:::Role with Name=RameshTestRole200 and Domain=ABCD alreadyexist.

In the example above the Role was not created, because Role Name is already exist in RL_PTY

table.


25/32


26/32


3.3.2 S a m p l e X M L R e t r i e v e R o l e E r r o r R e s p o n s e

When role for some reason could not be created, an error message is returned. Each error messagecontains Errors section with short description of a problem which was encountered during role

reading process. For User Roles, Role Reader Service each Error message is prefixed with R:::.

The sample error message has been placed below:

R:::Role with Name=RameshTestRole2001 and Domain=ABCD does notexist.

Failed

In the above example the Role, which was supposed to be retrieved, does not exist in the User Roles

database.

3.4 Up dat in g Ro l es

A web client can update a all permission codes associated to role. As of now, User Roles module is

supporting only full update, not partial update. A Role can be updated from Status AC or IN to AC or

IN or DL. If the new status is DL, the User Roles calls Delete Service automatically and delete role

permanently as part of update request.


27/32


3.4.1 Ho w To Upd at e a Ro le

The Role update request looks as follows:

In order to successfully update profile (Full Update) it is necessary to use proper values in the

updateRQ. The following attributes are crucial: RoleName, DomainID and Role Status Code. These

three values identify a concrete role.

Within the Full Update process there are two main stages. The first one is responsible for deletion of

old permissions data, whereas the second one for saving new permissions code.

3.4.2 S a m p l e X M L U p d a t e R o l e S u c c e s s f u l R e s p o n s e

A successful update results in the following response. Notice the element:

3.4.3 S a m p l e X M L U p d a t e R o l e E r r o r R e s p o n s e

When role for some reason could not be updated, an error message is returned. Each error message

contains Errors section with short description of a problem which was encountered during role

update process. For User Roles, Role Update Service each Error message is prefixed with U:::.

The sample error message has been placed below:

U:::Role with Name=RameshTestRole10212 and Domain=RameshTestRole10212 doesnot exist.


28/32


3.5 Sea rch in g Fo r Ro le

Search functionality allows user to specify search criteria and to find the matching roles and

permission in the User Roles. For both cases, Search response have maximum 250 Roles/Permission

codes. If search response has more than 250 then, User Roles search response has warning message.

3.5.1 Sa m p le XML Ro l e Se a r c h Re q u e s t

Below request shows how to search Roles.

3.5.2 S a m p l e X M L P e r m i s s i o n S e a r c h R e q u e s t

Below request shows how to search Permissions.

3.5.3 S a m p l e X M L R o l e S e a r c h L i s t R e s p o n s e

Below response shows successful Roles search result.


29/32


3.5.4 S a m p l e X M L P e r m i s s i o n S e a r c h L i s t R e s p o n s e

Below response shows successful Permissions search result.

3.5.8 S a m p l e X M L P e r m i s s i o n S e a r c h E r r o r R e s p o n s e

Below response shows Permissions search error.


30/32


S:::Permission Codes with ApplicationID=PPA does not exist

Failed

3.5.9 S a m p l e X M L R o l e s S e a r c h E r r o r R e s p o n s e

Below response shows Roles search error.

S:::Role with Name=RameshTestRole* and Domain=ABCDE does not

exist.

Failed

3.6 De le te Ro le

Delete Role functionality allows Deleting all Permissions asscociated to Role including Role details.

This is not soft delete in database, no way to recover role once deleted. To Delete Roles, Request

should have Role Name and Domain ID.

3.6.1 Sa m p le XML F o r Ro le De le t e Re q u e s t

The sample Role Delete request looks as follows:

3.6.2 S a m p l e X M L F o r R o l e D e l e t e S u c c e s s f u l R e s p o n s e

The sample Role Delete response looks as follows:


31/32


3.6.3 S a m p l e X M L M a r k P r o f i l e F o r D e l e t e E r r o r R e s p o n s e

If profile for some reason cannot be marked for delete, an error message is returned. The

section contains a brief description of a problem which was encountered during that process. The

sample error message has been shown below:

R:::Role with Name=RameshTestRole103 and Domain=ABCD does notexist.


32/32

Documents

UserRoles Techincal Documentation External V1.0