User Roles Web Services Technical Documentation User Roles Web Services Guide For External Users June 10th, 2008 Version 1.0 User Roles Web Services Web Services technical Guide 29 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. • User Roles Web Services • • Web Services technical Guide 29 User Roles Technical User Guide DOCUMENT REVISION INFORMATION 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. Revised by Date Revised Revision Reason Revision Control No. Revised by Date Revised Revision Reason Revision Control No. Revised by Date Revised Revision Reason Revision Control No. Revised by Date Revised Revision Reason Revision Control No. Revised by Date Revised Revision Reason Revision Control No. ii User Roles Web Services Web Services Technical Users Guide June 10, 2009 • Sabre Inc. Confidential/All Rights Reserved • • Table of Contents iii Table of Contents 1 Introduction ................................................................. 1 1.1 About This Guide .......................................................................................................................1 1.2 Standards and Specifications ...................................................................................................1 2 Accessing User Roles Web Services ................................. 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 Role Services ............................................................. 17 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 iv User Roles Web Services Web Services Technical Users Guide June 10, 2009 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 Sabre Inc. Confidential/All Rights Reserved Table of Contents v 1 1 Introduction 1.1 A b o u t T h i s G u i d e 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 t a n d a r d 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 Sabre Inc. Confidential/All Rights Reserved Introduction 1 A-2 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 IntroductionTechnical Reference Guide Template Writer Guide 07/29/08 Revision: UserRoles Techincal Documentation_External_V1.0.doc 2 2 Accessing User Roles Web Services 2.1 A b o u t U s e r R o l e s W e b S e r v i c e s Web clients access the content and functionality of the User roles web application by accessing the User Roles exposed through the Sabre Web Services (SWS) infrastructure. The Sabre Web Services infrastructure provides security, sessions, logging, and routing to the User Roles web business services located within Sabre Holdings The following shows the messaging flow to access User Roles Web Services: 1. The web client first requests access, a connection, and a session by sending a SessionCreateRQ XML request to the Sabre Web Services infrastructure which does the following: • Validates the user security credentials and message format • Authenticates the message • Authorizes access • Peserves the requestor composed unique conversation ID 2. The SWS infrastructure creates a new Web Services session. 3. The SWS infrastructure returns a security token in the SessionCreateRS XML response representing the connection, the session, the authentication and the authorization to the client. 4. The web client sends subsequent User Roles Web Service requests incorporating the returned SWS security token as well as the unique conversation ID sent with the initial SessionCreateRQ request. 5. The SWS infrastructure uses the security token and conversation ID to locate the persisted Web Services session, and, if granted access, routes each of the subsequent User Roles Service requests to the appropriate User Roles Web Services. 6. The User Roles Web service performs the request and returns the response to the Web Client. 7. The Web Services session ends when the web client sends the SessionCloseRQ XML request, or the session time out expires before the next User Roles Service web request is received. The web client delivers requests to the User Roles Web Services using the HTTPS protocol. All requests are sent to a URL that is the single access point to Sabre Web Services. URLs for several environments are available for web client testing and production as follows: Sabre Inc. Confidential/All Rights Reserved About User Roles Web Services 3 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. Client applications, then, consume all User Roles Web Services with XML/SOAP or WSDL/SOAP. 2.2 T y p e s o f W e b S e r v i c e 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 Session management Services 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 User Roles Services User Roles web clients can request via the internet the following profile services: • 4 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 OTA Profile Services OTA Profile Services Guidelines June 10, 2009 Sabre_RoleCreateRS XML response message back indicating success or failure and some rolerelated 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 e s s a g e S t r u c t u r e 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 XML which is based on but not 100% 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 Roles XML. 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. Sabre Inc. Confidential/All Rights Reserved Message Structure 5 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 S e c u r i t y Sabre Web Services have implemented multiple layers of security for client applications. These layers include line security, authentication, authorization, and confidentiality. 2.5.1 Line Security 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 Authentication 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 6 OTA Profile Services OTA Profile Services Guidelines June 10, 2009 elements present in the SOAP envelope in the SessionCreateRQ request message. You receive the values for the security credentals when you are set up by Sabre to use the User Roles Web Services. The Sabre Web Services infrastructure authenticates the service requestor using the security credentials found in the envelope of the request. An XML fragment of the security credentials from the SOAP SessionCreateRQ message envelope follows: <wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext" xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/12/utility"> <wsse:UsernameToken> <wsse:Username>USERNAME</wsse:Username> <wsse:Password>PASSWORD</wsse:Password> <Organization>USERORGANIZATION</Organization> <Domain>USERDOMAIN</Domain> </wsse:UsernameToken> </wsse:Security> NOTE: The following is the second multipart MIME part containing the Sabre XML payload message: <SessionCreateRQ> <POS> <Source PseudoCityCode="IM07"/> </POS> </SessionCreateRQ> 2.5.3 Authorization The authorization layer gives web clients access to specific web services. When a web client sends a request, the Sabre Web Services infrastructure authorizes access to all services in the product packages to which an organization has subscribed. Currently all User Roles Services are authorized as a package. 2.5.4 Confidentiality The confidentiality layer maintains the privacy of the data in a payload during its transmission. User Roles Web Services use HTTPS with 128-bit encryption. 2.6 N e t w o r k C o n n e c t i v i t y Access to the User Roles Web Services for web client applications is available through the Internet. Consequently, resources used to develop and deploy production applications must have Internet access. If you are behind a corporate firewall, you need information about your proxy server so that your applications can access the Internet. Sabre Inc. Confidential/All Rights Reserved Network Connectivity 7 2.7 W e b S e r v i c e s S e s s i o n s 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 security credentials, 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 reauthentication 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 services exchange messages that represent a business workflow. 4. When the SWS session is no longer needed, the client closes the session by sending the SessionCloseRQ 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 business process flow represented by the session is not guaranteed to be alive. 8 OTA Profile Services OTA Profile Services Guidelines June 10, 2009 2.7.1 SessionCreateRQ Request XML Example The web client establishes an SWS session by sending security credentials and a unique conversation ID as shown in the following example: The envelope <?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:eb="http://www.ebxml.org/namespaces/messageHeader" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> <SOAP-ENV:Header> <eb:MessageHeader SOAP-ENV:mustUnderstand="1" eb:version="1.0"> <eb:From> <eb:PartyId type="urn:x12.org:IO5:01">999999</eb:PartyId> </eb:From> <eb:To> <eb:PartyId type="urn:x12.org:IO5:01">123123</eb:PartyId> </eb:To> <eb:ConversationId>2007-12-15T11:15:12@clientURL.com</eb:ConversationId> <eb:CPAId> SabreSuppliedDomain </eb:CPAId> <eb:Service eb:type=" sabreXML">Session</eb:Service> <eb:Action>SessionCreateRQ</eb:Action> <eb:MessageData> <eb:MessageId>99999999</eb:MessageId> <eb:Timestamp>2007-12-15T11:15:12Z</eb:Timestamp> <eb:TimeToLive>2007-12-15T11:15:12Z</eb:TimeToLive> </eb:MessageData> </eb:MessageHeader> <wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext" xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/12/utility"> <wsse:UsernameToken> <wsse:Username>SabreSuppliedUserName</wsse:Username> <wsse:Password>SabreSuppliedPassword</wsse:Password> <Organization>SabreSuppliedOrganization</Organization> <Domain>SabreSuppliedDomain/Domain> </wsse:UsernameToken> </wsse:Security> </SOAP-ENV:Header> <eb:Manifest SOAP-ENV:mustUnderstand="1" eb:version="1.0"> <eb:Reference xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="cid:rootelement" xlink:type="simple"/> </eb:Manifest> <SOAP-ENV:Body> </SOAP-ENV:Body> </SOAP-ENV:Envelope> The SOAP payload <SessionCreateRQ> <POS> <Source PseudoCityCode="SabreSuppliedPseudoCity"/> </POS> </SessionCreateRQ> Sabre Inc. Confidential/All Rights Reserved Web Services Sessions 9 A typical response is: SOAP envelope <?xml version="1.0" encoding="UTF-8"?> <soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"> <soap-env:Header> <eb:MessageHeader xmlns:eb="http://www.ebxml.org/namespaces/messageHeader" eb:version="1.0" soapenv:mustUnderstand="1"> <eb:From> <eb:PartyId eb:type="URI">123123</eb:PartyId> </eb:From> <eb:To> <eb:PartyId eb:type="URI">999999</eb:PartyId> </eb:To> <eb:CPAId> SabreSuppliedPseudoCity</eb:CPAId> <eb:ConversationId>2007-12-15T11:15:12@clientURL.com</eb:ConversationId> <eb:Service eb:type="sabreXML">Session</eb:Service> <eb:Action>SessionCreateRS</eb:Action> <eb:MessageData> <eb:MessageId>97d9da35-3a36-4092-a934-99ba554ac712@73</eb:MessageId> <eb:Timestamp>2006-12-28T18:34:16</eb:Timestamp> <eb:RefToMessageId>99999999</eb:RefToMessageId> </eb:MessageData> </eb:MessageHeader> <wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext"> <wsse:BinarySecurityToken valueType="String" EncodingType="wsse:Base64Binary">Shared/IDL:IceSess\/SessMgr:1\.0.IDL/Common/!ICESMS\/STSB!ICESMSLB\/S TS.LB!-4617338326250370976!113241!0</wsse:BinarySecurityToken> </wsse:Security> </soap-env:Header> <soap-env:Body> <eb:Manifest xmlns:eb="http://www.ebxml.org/namespaces/messageHeader" eb:id="Manifest" eb:version="1.0"> <eb:Reference eb:id="SessionCreateRS" xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="cid:SessionCreateRS"> <eb:Description xml:lang="en-US">Session Create Response Message</eb:Description> </eb:Reference> </eb:Manifest> </soap-env:Body> </soap-env:Envelope> SOAP payload <SessionCreateRS xmlns="http://www.opentravel.org/OTA/2002/11" version="1" status="Approved"> <ConversationId>2007-02-15T11:15:12@clientURL.com</ConversationId> </SessionCreateRS 10 OTA Profile Services OTA Profile Services Guidelines June 10, 2009 2.7.2 User Roles Service Requests Using A Session 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: <?xml version=”1.0” encoding='UTF-8'?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:eb="http://www.ebxml.org/namespaces/messageHeader" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> <SOAP-ENV:Header> <eb:MessageHeader SOAP-ENV:mustUnderstand="1" eb:version="2.0"> <eb:ConversationId>2007-02-15T11:15:12@clientURL.com</eb:ConversationId> <eb:From> <eb:PartyId type="urn:x12.org:IO5.01”>clientURL</eb:PartyId> </eb:From> <eb:To> <eb:PartyId type="urn:x12.org:IO5.01">webservices.sabre.com</ eb:PartyId> </eb:To> <eb:CPAId>IPCC</eb:CPAId> <eb:Service eb:type="sabreXML">Session</eb:Service> <eb:Action>Role_EXT_CreateRQ </eb:Action> <eb:MessageData> <eb:MessageId>mid:20001209-133003-2333@clientURL </eb:MessageId> <eb:Timestamp>2004-02-15T11:15:12Z</eb:Timestamp> <eb:TimeToLive>2004-02-15T11:15:12Z</eb:TimeToLive> </eb:MessageData> </eb:MessageHeader> <wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext" xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/12/utility"> <wsse:BinarySecurityToken xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/12/utility" wsu:Id="SabreSecurityToken" valueType="String" EncodingType="wsse:Base64Binary"> Shared/IDL:IceSess\/SessMgr:1\.0.IDL/Common/!ICESMS\/STSB!ICESMSLB\/STS.LB!4617338326250370976!113241!0 </ wsse:BinarySecurityToken> </wsse:Security> </SOAP-ENV:Header> <SOAP-ENV:Body> <eb:Manifest SOAP-ENV:mustUnderstand="1" eb:version="2.0"> <eb:Reference xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="cid: RoleCreateRQ " xlink:type="simple"/> </eb:Manifest> </SOAP-ENV:Body> </SOAP-ENV:Envelope> NOTE: The following is the second multipart MIME part containing the Sabre Profile XML message: <Sabre_RolesCreateRQ> ………. <contents of the XML> </ Sabre_RolesCreateRQ> Sabre Inc. Confidential/All Rights Reserved Web Services Sessions 11 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 Ending the Session 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: <?xml version=”1.0” encoding='UTF-8'?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:eb="http://www.ebxml.org/namespaces/messageHeader" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> <SOAP-ENV:Header> <eb:MessageHeader SOAP-ENV:mustUnderstand="1" eb:version="2.0"> <eb:ConversationId>2007-02-15T11:15:12@clientURL.com </eb:ConversationId> <eb:From> <eb:PartyId type="urn:x12.org:IO5.01">clientURL</eb:PartyId> </eb:From> <eb:To> <eb:PartyId type="urn:x12.org:IO5.01">webservices.sabre.com</ eb:PartyId> </eb:To> <eb:CPAId>IPCC</eb:CPAId> <eb:Service eb:type="sabreXML">Session</eb:Service> <eb:Action>SessionCloseRQ</eb:Action> <eb:MessageData> <eb:MessageId>mid:20001209-133003-2333@clientURL</eb:MessageId> <eb:Timestamp>2004-02-15T11:15:12Z</eb:Timestamp> <eb:TimeToLive>2004-02-15T11:15:12Z</eb:TimeToLive> </eb:MessageData> </eb:MessageHeader> <wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext" xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/12/utility"> <wsse:BinarySecurityToken xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/12/utility" wsu:Id="SabreSecurityToken" valueType="String" EncodingType="wsse:Base64Binary"> Shared/IDL:IceSess\/SessMgr:1\.0.IDL/Common/!ICESMS\/STSB!ICESMSLB\/STS.LB!4617338326250370976!113241!0 </ wsse:BinarySecurityToken> </wsse:Security> </SOAP-ENV:Header> <SOAP-ENV:Body> <eb:Manifest SOAP-ENV:mustUnderstand="1" eb:version="2.0"> <eb:Reference xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="cid:SessionCloseRQ" xlink:type="simple"/> </eb:Manifest> </SOAP-ENV:Body> </SOAP-ENV:Envelope> 12 OTA Profile Services OTA Profile Services Guidelines June 10, 2009 NOTE: The following is the second multipart MIME part containing the Sabre XML message:\ <?xml version="1.0" encoding="UTF-8"?> <SessionCreateRS xmlns="http://www.opentravel.org/OTA/2002/11" version="1" status="Approved"> <ConversationId>2007-02-15T11:15:12@clientURL.com </ConversationId> </SessionCreateRS> 2.8 W e b S e r v 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 Services infrastructure, 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 them as SOAP faults, with or without ebXML headers. • Business application errors – These errors are generated by the business application services that are 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 are external to the User Roles Web Services. They normally occur in the development environment, and are returned to the client. When the response contains the <soap-env:fault> 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. Sabre Inc. Confidential/All Rights Reserved Web Services Error Handling 13 3 User Roles 3 3.1 U s e r R o l e s D a t a O v e r v 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: 14 o Permission Code o Application Code OTA Profile Services OTA Profile Services Guidelines June 10, 2009 3.2 C r e a t i n g R o l e 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 How To Create a Role with Permission Codes Assume the SessionCreateRQ has already returned the binary session token and conversation ID for the 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 Sample XML Create Role Request The Create Traveler XML request begins with the following boilerplate: <?xml version="1.0" encoding="UTF-8"?> <Sabre_RolesCreateRQ TimeStamp="2001-12-17T09:30:47-05:00" Target="Production" Version="3.1415926535897932384626433832795" xmlns="http://www.sabre.com/UserRoles/schemas"> <!--Attribute TimeStamp is optional, type: dateTime --> <!--Attribute Target is optional, type:Target --> <!--Attribute Version is required, type: decimal --> Right after this section comes base element <Roles>. There are no attributes in <Roles> element. Now define the unique identification for this role. This is <RolesIdentity> element. <RolesIdentity RoleName="RameshTestRole102" DomainID="ABCD" RoleStatusCode="AC"/> <!-- Attribute RoleName is required, type: StringLength1to30 --> <!-- Attribute DomainID is required, type: StringLength1to20 --> <!-- Attribute RoleStatusCode is optional, type: StatusType --> 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. Sabre Inc. Confidential/All Rights Reserved User Roles 15 The Permissions section section looks as follows. <Roles> element can hold maximum 50 <AssociatedPermissions> <AssociatedPermissions PermissionCode="CPRF" ApplicationCode="PPP"/> <!-- Attribute PermissionCode is required, type: StringLength1to10 --> <!-- Attribute ApplicationCode is required, type: StringLength1to10 --> 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 Sample XML Create Role Successful Response When role is successfully created, the following response message is returned: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Sabre_RolesCreateRS Version="1.0" TimeStamp="2009-02-16T18:04:09.630-06:00" xmlns="http://www.sabre.com/UserRoles/schemas"> <ResponseMessage> <Success/> </ResponseMessage> <Roles RoleStatusCode="AC" DomainID="ABCD" RoleName="RameshTestRole1"/> </Sabre_RolesCreateRS> 3.2.4 Sample XML Create Role Error Response 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: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Sabre_RolesCreateRS Version="1.0" TimeStamp="2009-03-01T23:09:58.198-06:00" xmlns="http://www.sabre.com/UserRoles/schemas"> <ResponseMessage> <Errors> <ErrorMessage>C:::Role with Name=RameshTestRole200 and Domain=ABCD already exist.</ErrorMessage> </Errors> </ResponseMessage> <Roles RoleStatusCode="AC" DomainID="ABCD" RoleName="RameshTestRole200"/> </Sabre_RolesCreateRS> In the example above the Role was not created, because Role Name is already exist in RL_PTY table. 16 OTA Profile Services OTA Profile Services Guidelines June 10, 2009 3.3 R e t r i e v i n g R o l e s Web clients can retrieve the role with permission code by specifying Role Name and Domain ID. The sample Role Read Request looks as follows: <?xml version="1.0" encoding="UTF-8"?> <!--Sample XML file generated by XMLSPY v2004 rel. 3 U (http://www.xmlspy.com)--> <Sabre_RolesReadRQ TimeStamp="2001-12-17T09:30:47-05:00" Target="Production" Version="3.1415926535897932384626433832795" xmlns="http://www.sabre.com/UserRoles/schemas"> <Roles RoleName="RameshTestRole" DomainID="ABCD"/> </Sabre_RolesReadRQ> 3.3.1 Sample XML Retrieve Role Successful Response When a role is successfully retrieved, the following response message is returned. <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Sabre_RolesReadRS Version="1.0" TimeStamp="2009-03-01T23:18:14.963-06:00" xmlns="http://www.sabre.com/UserRoles/schemas"> <ResponseMessage> <Success/> </ResponseMessage> <Roles> <RolesIdentity DomainID="ABCD" RoleName="RameshTestRole200"/> <AssociatedPermissions ApplicationCode="PPP" PermissionCode="CPRF"/> </Roles> </Sabre_RolesReadRS> The most important section is the Rolessection which contains the retrieved Role. Sabre Inc. Confidential/All Rights Reserved User Roles 17 3.3.2 Sample XML Retrieve Role Error Response 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 role reading process. For User Roles, Role Reader Service each Error message is prefixed with “R:::”. The sample error message has been placed below: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Sabre_RolesReadRS Version="1.0" TimeStamp="2009-03-01T23:21:08.077-06:00" xmlns="http://www.sabre.com/UserRoles/schemas"> <ResponseMessage> <Errors> <ErrorMessage>R:::Role with Name=RameshTestRole2001 and Domain=ABCD does not exist.</ErrorMessage> </Errors> </ResponseMessage> <Message>Failed</Message> </Sabre_RolesReadRS> In the above example the Role, which was supposed to be retrieved, does not exist in the User Roles database. 3.4 U p d a t i n g R o l e s 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. 18 OTA Profile Services OTA Profile Services Guidelines June 10, 2009 3.4.1 How To Update a Role The Role update request looks as follows: <?xml version="1.0" encoding="UTF-8"?> <!--Sample XML file generated by XMLSPY v2004 rel. 3 U (http://www.xmlspy.com)--> <Sabre_RolesUpdateRQ TimeStamp="2001-12-17T09:30:47-05:00" Target="Production" Version="3.1415926535897932384626433832795" xmlns="http://www.sabre.com/UserRoles/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.sabre.com/UserRoles/schemas C:\code\Roles\schemas\Beta_V0.1\schemasWSDL\Sabre_RolesUpdateRQ.xsd"> <Roles> <RolesIdentity RoleName="RameshTestRole102" DomainID="ABCD" RoleStatusCode="AC"/> <AssociatedPermissions PermissionCode="CPRF" ApplicationCode="PPP"/> <AssociatedPermissions PermissionCode="DPRF" ApplicationCode="PPP"/> <AssociatedPermissions PermissionCode="UPRF" ApplicationCode="PPP"/> <AssociatedPermissions PermissionCode="RPRF" ApplicationCode="PPP"/> </Roles> </Sabre_RolesUpdateRQ> 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 Sample XML Update Role Successful Response A successful update results in the following response. Notice the <Success> element: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Sabre_RolesUpdateRS Version="1.0" TimeStamp="2009-02-19T01:38:17.872-06:00" xmlns="http://www.sabre.com/UserRoles/schemas"> <ResponseMessage> <Success/> </ResponseMessage> <Roles RoleStatusCode="AC" DomainID="ABCD" RoleName="RameshTestRole102"/> </Sabre_RolesUpdateRS> 3.4.3 Sample XML Update Role Error Response 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: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Sabre_RolesUpdateRS Version="1.0" TimeStamp="2009-03-03T13:12:02.016-06:00" xmlns="http://www.sabre.com/UserRoles/schemas"> <ResponseMessage> <Errors> <ErrorMessage>U:::Role with Name=RameshTestRole10212 and Domain=RameshTestRole10212 does not exist.</ErrorMessage> </Errors> Sabre Inc. Confidential/All Rights Reserved User Roles 19 </ResponseMessage> <Roles RoleStatusCode="AC" DomainID="ABCD" RoleName="RameshTestRole10212"/> </Sabre_RolesUpdateRS> 3.5 S e a r c h i n g F o r R o l e 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 Sample XML Role Search Request Below request shows how to search Roles. <?xml version="1.0" encoding="UTF-8"?> <!--Sample XML file generated by XMLSPY v2004 rel. 3 U (http://www.xmlspy.com)--> <Sabre_RolesSearchRQ TimeStamp="2001-12-17T09:30:47-05:00" Target="Production" Version="3.1415926535897932384626433832795" xmlns="http://www.sabre.com/UserRoles/schemas"> <RolesSearchCriteria RoleName="TestRole" DomainID="*"/> </Sabre_RolesSearchRQ> 3.5.2 Sample XML Permission Search Request Below request shows how to search Permissions. <?xml version="1.0" encoding="UTF-8"?> <!--Sample XML file generated by XMLSPY v2004 rel. 3 U (http://www.xmlspy.com)--> <Sabre_RolesSearchRQ TimeStamp="2001-12-17T09:30:47-05:00" Target="Production" Version="3.1415926535897932384626433832795" xmlns="http://www.sabre.com/UserRoles/schemas"> <PermissionsSearchCriteria ApplicationCode="PPP"/> </Sabre_RolesSearchRQ> 3.5.3 Sample XML Role Search List Response Below response shows successful Roles search result. <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Sabre_RolesSearchRS Version="1.0" TimeStamp="2009-02-19T01:36:01.392-06:00" xmlns="http://www.sabre.com/UserRoles/schemas"> <ResponseMessage> <Success/> </ResponseMessage> <RolesInfo> <RolesList DomainID="ABCD" RoleName="RameshTestRole1"/> <RolesList DomainID="ABCD" RoleName="RameshTestRole101"/> <RolesList DomainID="ABCD" RoleName="RameshTestRole101*"/> <RolesList DomainID="ABCD" RoleName="RameshTestRole102"/> </RolesInfo> </Sabre_RolesSearchRS> 20 OTA Profile Services OTA Profile Services Guidelines June 10, 2009 3.5.4 Sample XML Permission Search List Response Below response shows successful Permissions search result. <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Sabre_RolesSearchRS Version="1.0" TimeStamp="2009-03-11T14:25:16.679-05:00" xmlns="http://www.sabre.com/UserRoles/schemas"> <ResponseMessage> <Success/> </ResponseMessage> <PermissionsInfo> <PermissionsList ApplicationCode="PPP" PermissionDescription="ALL OPERATIONS ON PROFILES" PermissionCode="CRUDPRF"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="DELETE PROFILES" PermissionCode="DPRF"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="ALL OPERATION ON TEMPLATES" PermissionCode="CRUDTPL"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="CREATE FORMATS" PermissionCode="CFMT"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="UPDATE FORMATS" PermissionCode="UFMT"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="DELETE FORMATS" PermissionCode="DFMT"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="READ FORMATS" PermissionCode="RFMT"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="ALL OPERATIONS ON FORMATS" PermissionCode="CRUDFMT"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="ALL OPERATIONS ON PPP SYSTEM" PermissionCode="ADMINPPP"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="UPDATE PROFILE" PermissionCode="UPRF"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="READ PROFILE" PermissionCode="RPRF"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="CREATE TEMPLATE" PermissionCode="CTPL"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="UPDATE TEMPLATE" PermissionCode="UTPL"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="DELETE TEMPLATE" PermissionCode="DTPL"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="READ TEMPLATE" PermissionCode="RTPL"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="CREATE FILTER" PermissionCode="CFLT"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="UPDATE FILTER" PermissionCode="UFLT"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="READ FILTER" PermissionCode="RFLT"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="DELETE FILTER" PermissionCode="DFLT"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="ALL OPERATIONS ON FILTERS" PermissionCode="CRUDFLT"/> <PermissionsList ApplicationCode="PPP" PermissionDescription="CREATE PROFILES" PermissionCode="CPRF"/> </PermissionsInfo> </Sabre_RolesSearchRS> 3.5.8 Sample XML Permission Search Error Response Below response shows Permissions search error. <?xml version="1.0" encoding="UTF-8" standalone="yes"?> Sabre Inc. Confidential/All Rights Reserved User Roles 21 <Sabre_RolesSearchRS Version="1.0" TimeStamp="2009-03-11T14:26:18.773-05:00" xmlns="http://www.sabre.com/UserRoles/schemas"> <ResponseMessage> <Errors> <ErrorMessage>S:::Permission Codes with ApplicationID=PPA does not exist</ErrorMessage> </Errors> </ResponseMessage> <PermissionsInfo> <Message>Failed</Message> </PermissionsInfo> </Sabre_RolesSearchRS> 3.5.9 Sample XML Roles Search Error Response Below response shows Roles search error. <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Sabre_RolesSearchRS Version="1.0" TimeStamp="2009-03-11T14:27:38.205-05:00" xmlns="http://www.sabre.com/UserRoles/schemas"> <ResponseMessage> <Errors> <ErrorMessage>S:::Role with Name=RameshTestRole* and Domain=ABCDE does not exist.</ErrorMessage> </Errors> </ResponseMessage> <RolesInfo> <Message>Failed</Message> </RolesInfo> </Sabre_RolesSearchRS> 3.6 D e l e t e R o l e 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 Sample XML For Role Delete Request The sample Role Delete request looks as follows: <?xml version="1.0" encoding="UTF-8"?> <!--Sample XML file generated by XMLSPY v2004 rel. 3 U (http://www.xmlspy.com)--> <Sabre_RolesDeleteRQ TimeStamp="2001-12-17T09:30:47-05:00" Target="Production" Version="3.1415926535897932384626433832795" xmlns="http://www.sabre.com/UserRoles/schemas"> <Roles RoleName="RameshTestRole105" DomainID="ABCD" /> </Sabre_RolesDeleteRQ> 3.6.2 Sample XML For Role Delete Successful Response The sample Role Delete response looks as follows: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Sabre_RolesDeleteRS Version="1.0" TimeStamp="2009-03-10T15:58:19.499-05:00" xmlns="http://www.sabre.com/UserRoles/schemas"> <ResponseMessage> <Success/> </ResponseMessage> <Roles DomainID="ABCD" RoleName="RameshTestRole105"/> 22 OTA Profile Services OTA Profile Services Guidelines June 10, 2009 </Sabre_RolesDeleteRS> 3.6.3 Sample XML Mark Profile For Delete Error Response If profile for some reason cannot be marked for delete, an error message is returned. The <Errors> section contains a brief description of a problem which was encountered during that process. The sample error message has been shown below: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Sabre_RolesDeleteRS Version="1.0" TimeStamp="2009-03-09T18:41:49.773-05:00" xmlns="http://www.sabre.com/UserRoles/schemas"> <ResponseMessage> <Errors> <ErrorMessage>R:::Role with Name=RameshTestRole103 and Domain=ABCD does not exist.</ErrorMessage> </Errors> </ResponseMessage> <Roles DomainID="ABCD" RoleName="RameshTestRole103"/> </Sabre_RolesDeleteRS> Sabre Inc. Confidential/All Rights Reserved User Roles 23 • 24 OTA Profile Services • • OTA Profile Services Guidelines June 10, 2009