User Profile Web Service Guide
- IT Info
- Malissa Olofernes
- Dave Nygaard
- Becca Cook (Unlicensed)
Overview
Deem provides the User Profile web service for partners and third-party application providers to create, update, disable, or retrieve user profiles. 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. This document provides a technical specification to help partners access the User Profile web service in Deem from web service clients.
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. 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.
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.
Note: For technical specifications for session management and single sign-on (SSO) integration, see Implementing Single Sign-On (SSO) for Desktop.
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.
Note: To configure this subscription at the super-domain level for multiple sites, file a support ticket to obtain the super-domain instructions for configuring web services.
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:
- 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.
- Click the Web Services link. The Settings | Web Services page appears.
Note: For more detailed instructions on using the Web Services page, see Web Services. - Click the Profile Pull Web Service link at the top of the page. The Settings | Profile Pull Web Services page appears.
- 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.
- 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:
- Add (or edit) the Subscription Name and contact information, 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.
- Enter the authentication user name and password, which is used to authenticate an incoming web service request.
Click the check box or choose a value for the following permissions:
- Click Save to save your settings. The Settings | Subscriptions page appears again, with your new (or edited) subscription in the list of subscriptions.
- Click the Back to Profile Pull Web Services link at the top of the page. The Settings | Profile Pull Web Services page appears.
- To add the subscription to a subscription set, click the Profile Pull Web Service Subscription Sets link.
- Click the Add A New Subscription Set link or click the name of an existing set. The Services | Add/Edit Subscription Set page appears.
- If you are creating a new set, enter the name of the set in the Set Name field.
- Click the Add Subscr. button. The Services | Search & Add Code To Set page appears.
- Click the radio button beside the name of the subscription you created or edited in Steps 5-9, and click OK to add it to the set. The Services | Add/Edit Subscription Set page appears again.
- Click Save to save the subscriptions in the set.
- Click the Rules tab to define this subscription set as part of a rule to be applied to a group of users. The Rules | Overview page appears.
- Click the Web Services Rules link to enable Web Services access. The Rules | Web Services Rules page appears, with groups of users listed (including the Everyone group, which includes all users).
Note: For more detailed instructions about using web services rules, see Web Services Rules-old. - To set up a Web Services rule with the subscription set for the Everyone group, click the Add or Edit link in the Travel column for the Everyone row; to set up a travel rule with the display configuration set for a different group, click the Add or Edit link in the Profile Pull Web Service column for that group's row. The Rules | Edit Profile Pull Web Service Rule page appears.
- Enter a Description that describes the rule and will be easily recognizable when it appears in a drop-down list. Be sure to click the Activate Rule check box.
- In the "Then..." section of the page, be sure that the radio button next to "Enable Web Services using the following configuration sets" is selected.
- Select from the Set drop-down list the subscription set you created or edited in Steps 12-16.
- Scroll to the bottom of the page and click Save to save the changes.
- Commit your changes (you can click the Changes not applied link in the top right corner of the page, and then click the Commit button).
Creating a Web Service Client
As a partner, you can create a web service client to access the User Profile web service using the supplied Web Service Definition Language (WSDL) file, User Profile Schema file, and Common Types Schema file. Follow these steps to download these files:
- Log into the Partner Dashboard as a site administrator. The Settings | Overview page appears.
- Click the Web Services link. The Web Services page appears.
- Click the Profile Pull Web Service link at the top of the page. The Profile Pull Web Services page appears.
- Click the Documentation link. The files are downloaded to your computer.
In addition, we provide the profile attributes in User Profile Fields, and the list of pre-defined values for profile attributes in Profile List of Values.
The following listing shows sample request and response SOAP messages. The Web Service client can include multiple user elements in customerSet — up to the maximum number of profiles per batch configured for the web services subscription. If a request includes multiple user profiles, the profiles are created or updated, and if all of the profiles are processed without errors, the response message includes the responseCode "OK". The ResponseDataSet contains a list of elements with companyID, externalID, and externalIDSet. If a profile is rejected or fails to be processed, the responseCode is set to "PROBLEM" and the response includes rejectedCustomerSet and/or failedProfileSet. RejectedCustomerSet is returned with full user element(s). FailedPorfileSet includes failedProfile with externalID and errorMessage.
Web Service Endpoint
The User Profile web service endpoint URL in production is: https://webservices.deem.com/webservices/services/userProfile.
The Deem Integration team is is responsible for configuring domain or super-domain web service subscriptions, enabling the web service rule, and providing the partner with authentication credentials. To enable a partner to test against Deem's QA endpoint, the Integration team provides an externally accessible QA environment and a User Profile web service endpoint URL for that environment.
Note: Even though the web service endpoint URL is https://webservices.deem.com/webservices/services/userProfile , please use http://webservices.reardencommerce.com/userprofile/ as the XML namespace URL in your SOAP request body (see the sample SOAP request).
Managing a User Profile
You can use SOAP requests to create new user profiles, update existing user profiles, disable user profiles, or retrieve user profiles. The attributes for a user profile are listed in User Profile Fields, and the fixed values for some attributes are listed in Profile List of Values.
Note: The SOAP request for all profile creations, updates, and disablements use the same "updateRequest" element in the request body (see the sample SOAP request).
Creating a New User Profile
Five attributes are required for creating a new user profile (see User Profile Fields for all attributes):
- external ID
- username
- first name
- last name
The external ID (externalID) is generated by the partner. It must be able to uniquely identify a user in a site. The username and email also needs to be unique per user in a site.
Updating an Existing User Profile
If a user profile with a given external ID already exists, the existing profile can be updated with profile information from a request message if the user.timestamp in the request (in GMT format) is later than the last modified time of the profile in the system. If it is not, the profile update is rejected.
To clear a child element's value of user, a string value of "NULL" must be included. Exceptions are for the child elements birthDay, title, and vipIndicator — in which case an empty value or exclusion of the element will clear the value. To clear an address, include an address element with empty child elements.
Collection types such as preferences, visas, passports, national ID cards, and charge cards, if included, needs to be provided with full lists of items. If an existing item is not provided in the collection, it will be deleted.
Note: The Account Status (accountStatus) field is uploaded only for clients using single sign-on (SSO), which does not require an activation email to activate new users (and therefore authentication is handled by the identity provider). Clients using SSO can set the user’s accountStatus to “A” and the user can access the site immediately. If you do not use SSO, use Employee Status (employeeStatus) and leave Account Status (accountStatus) blank.
Disabling an Existing User Profile
If the user.accountStatus has the value "Inactive", or user.employeeStatus has value "D", the user profile will be disabled.
Sample Update Request SOAP Message
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:AuthHeader xmlns:h="http://webservices.reardencommerce.com/userprofile/" xmlns="http://webservices.reardencommerce.com/userprofile/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<login>kentest</login>
<password>MySharedSecret</password>
<companyDomain>TestSite</companyDomain>
</h:AuthHeader>
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<updateRequest xmlns="http://webservices.reardencommerce.com/userprofile/">
<customerSet>
<user>
<externalID>testuser</externalID>
<domain>testcompany</domain>
<accountStatus>Active</accountStatus>
<employeeStatus>A</employeeStatus>
<userInfo>
<userName>testuser</userName>
<firstName>test</firstName>
<lastName>user</lastName>
<email>test.user@deem.com</email>
<gender>M</gender>
<jobTitle>engineer</jobTitle>
<workPhone>
<number>6505555555</number>
<countryCode>1</countryCode>
<extension>123</extension>
</workPhone>
<mobilePhone>
<number>6505551111</number>
<countryCode>1</countryCode>
</mobilePhone>
<companyName>testcompany</companyName>
<address>
<street1>22 test street</street1>
<aptSuite>401</aptSuite>
<city>fake city</city>
<stateProvince>CA</stateProvince>
<postalCode>92222</postalCode>
<country>US</country>
</address>
<emergencyContactName>Mrs. Smith</emergencyContactName>
<emergencyContactRelationship>Spouse/Domestic Partner</emergencyContactRelationship>
<emergencyContactPrimaryPhone>
<number>6505557777</number>
</emergencyContactPrimaryPhone>
</userInfo>
<servicePreferences>
<airlinePreferences>
<homeAirport>SFO</homeAirport>
<mealPreference>LCML</mealPreference>
<seatPreference>Aisle</seatPreference>
</airlinePreferences>
<carRentalPreferences>
<defaultCarType>S</defaultCarType>
</carRentalPreferences>
</servicePreferences>
<passportSet>
<passport>
<countryCode>US</countryCode>
<number>P12345</number>
<expirationDate>2015-05-12</expirationDate>
<issueDate>2011-05-12</issueDate>
<issueCountry>US</issueCountry>
</passport>
</passportSet>
<chargeCardSet>
<chargeCard>
<cardNumber>5111000000000000</cardNumber>
<brandType>CA</brandType>
<expirationDate>2014-01-30</expirationDate>
<cardName>My Master Card</cardName>
<billingAddress>
<street1>123 main street</street1>
<city>Fake City</city>
<stateProvince>CA</stateProvince>
<postalCode>92222</postalCode>
<country>US</country>
</billingAddress>
<billingName>test user</billingName>
</chargeCard>
</chargeCardSet>
<timestamp>2012-06-01T22:17:07.00</timestamp>
</user>
</customerSet>
</updateRequest>
</s:Body>
</s:Envelope>
Sample Update Response SOAP Message
Retrieving a Batch of User Profiles
If you need to retrieve any user profile data, you can send a “getPageRequest”. The first time you send this request, you need to specify a timestamp. The timestamp returns only profiles that were modified after the specified date and time. In the response, you receive a batch of user profiles (up to the maximum amount configured for your subscription; default is 100).
In addition, two important metadata fields are returned at the bottom of the response:
| Field Name | Description |
|---|---|
| recordsRemaining | Indicates if there are any more profiles remaining to retrieve that were modified after the previous “getPageRequest”. If the value is “true”, there are more profiles to retrieve. If the value is “false”, there are no profiles to retrieve at this time. |
| conversationID | This ID is established between the partner application and Deem after the very first “getPageRequest” is processed. This same ID value should be sent in subsequent requests to retrieve any remaining profile data. |
Note: After you receive a conversationID from your very first response, you should continue to send that conversationID in every subsequent request to avoid performing duplicate retrievals of the same profiles. We recommend that you not establish a new conversationID.
Tip: If a response returns a value of “false” for the “recordsRemaining” field, you can still make subsequent requests (using the same conversationID) if any previously pulled profiles have been recently updated. This is useful if you want to retrieve updated profiles as they become available.
Sample Initial Get Request SOAP Message
Sample Initial Get Response SOAP Message
Sample Subsequent Get Request SOAP Message
Sample Subsequent Get Request SOAP Message