User Profile Web Service Guide Deem@Work Small Business Suite REARDEN COMMERCE USER PROFILE WEB SERVICE GUIDE – DEEM@WORK SMALL BUSINESS SUITE
Total Page:16
File Type:pdf, Size:1020Kb
04-MAR-2013 User Profile Web Service Guide Deem@Work Small Business Suite REARDEN COMMERCE USER PROFILE WEB SERVICE GUIDE – DEEM@WORK SMALL BUSINESS SUITE Table of Contents Overview ..........................................................................................................................................................3 Configuring the Web Service Subscription .......................................................................................................4 Site Subscription .........................................................................................................................................4 Super-domain Subscription ........................................................................................................................6 Creating a Web Service Client .........................................................................................................................9 Web Service Endpoint ................................................................................................................................9 Sample Request SOAP Message ..............................................................................................................9 Sample Response SOAP Message ..........................................................................................................13 Managing a User Profile .................................................................................................................................14 Creating a New User Profile .....................................................................................................................14 Updating an Existing User Profile .............................................................................................................14 Disabling an Existing User Profile ............................................................................................................14 Appendix A: WSDL File (userProfile.wsdl) .....................................................................................................15 Appendix B: User Profile Schema ..................................................................................................................17 Appendix C: Common Types Schema ...........................................................................................................20 Appendix D: User Profile Attributes ................................................................................................................39 Appendix E: Profile List of Values ..................................................................................................................56 Title and Suffix ..........................................................................................................................................56 Emergency Contact Relationship .............................................................................................................56 Credit Card Vendor Codes .......................................................................................................................57 Air Special Request ..................................................................................................................................57 Visa Types ................................................................................................................................................58 Meal Preference .......................................................................................................................................59 Hotel Special Request ..............................................................................................................................60 Hotel Amenities ........................................................................................................................................61 Rental Car Special Request .....................................................................................................................62 Default Car Types .....................................................................................................................................63 Rental Car Company Codes ....................................................................................................................64 Hotel Chain Codes ...................................................................................................................................66 Airline Vendor Codes ...............................................................................................................................74 Copyright © 2013 Rearden Commerce, Inc. All rights reserved. 2 REARDEN COMMERCE USER PROFILE WEB SERVICE GUIDE – DEEM@WORK SMALL BUSINESS SUITE Overview Rearden Commerce provides the User Profile web service for partners and third-party application providers to create, update, or disable user profiles in Deem@Work. A user profile is a collection of personal data associated to a specific user. User profiles provide the raw user data upon which services transact. Profile data must be securely managed by applications and services. The User Profile web service uses Extensible Markup Language (XML) messages that follow the Simple Object Access Protocol (SOAP) standard, which is a protocol specification for exchanging structured information.1 Partners or application providers can create web service clients to access the User Profile web service using the Web Service Definition Language (WSDL) file and schema provided with this document. WSDL is an XML format for describing network services as a set of endpoints operating on messages. A WSDL description of a web service (also referred to as a WSDL file) provides a machine-readable description of how the service can be called, what parameters it expects, and what data structures it returns.2 Using the User Profile web service, web service clients can get information about the user's profile, and can push updates back to the user’s profile. Clients must specify which information they would like to retrieve for a given profile in each request. This avoids the added latency of multiple API calls without the performance overhead of retrieving unnecessary information in each request. The user is identified by an ID (externalID) passed to the application during single sign-on in the Security Assertion Markup Language (SAML) identity assertion. Technical specifications for session management and single sign-on (SSO) integration is provided in the Session Management Guide for Deem@Work. This document provides a technical specification to help partners access the User Profile web service in Deem@Work from web service clients. 1 For a definition of SOAP, see http://en.wikipedia.org/wiki/SOAP. 2 For details on WSDL, see http://www.w3.org/TR/wsdl. 3 REARDEN COMMERCE USER PROFILE WEB SERVICE GUIDE – DEEM@WORK SMALL BUSINESS SUITE Configuring the Web Service Subscription To use the User Profile web service, a partner must configure a subscription to the service. The partner can configure this subscription at the site level for a single site, or at the super-domain level for multiple sites. Site Subscription In order to configure a subscription at the site level for a single site, you need to add the subscription to a subscription set, and associate the subscription set with a user group through a web service rule. Follow these steps: 1. From the Partner Dashboard, locate the site and click the Settings link for the appropriate site, or log in directly to the Site Dashboard. The Settings | Overview page appears. 2. Click the Web Services link. The Settings | Web Services page appears. 3. Click the Profile Pull Web Service link at the top of the page. The Settings | Profile Pull Web Services page appears. 4. Click the Profile Pull Web Service Subscriptions link at the top of the page. The Settings | Subscriptions page appears with other subscriptions you’ve created. 5. Click an existing subscription and the Settings | Edit Subscription page appears, or click the Add A New Subscription link at the bottom of the page, and the Settings | Add Subscription page appears, as shown in Figure 1. 6. Add (or edit) the Subscription Name and contact information (refer to Figure 1), set the Web Service Type to User Profile, set the Mode to Live, and set the Inbound Message Unique Key to External ID. The External ID is generated by the partner and needs to be unique in a site for a user. 7. Enter the authentication user name and password (refer to Figure 1), which is used to authenticate an incoming web service request. 8. Click the check box or choose a value for the following permissions (refer to Figure 1): • Set the # of profiles to send per batch. This is the maximum number of profiles that can be retrieved in a Get request (the default is 100). • Allow “update” of existing <partner> user profiles. • Allow “add” of new <partner> user profiles if they don’t already exist. • Allow “delete/disable” of <partner> user profiles. • (Optional) Restrict “updates” to match Profile Field Settings (“Profile Load” permissions). Click the check box for this option if a profile update via the web service should be restricted to the fields defined in “Profile Field Settings”. • Set the # of failed login attempts before locking the account (suggested value: 3). • Set the lock for a number of minutes (suggested value: 10 minutes). 4 REARDEN COMMERCE USER PROFILE WEB SERVICE GUIDE – DEEM@WORK SMALL BUSINESS SUITE Figure 1. Add (or edit)