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.
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:
Click the check box or choose a value for the following permissions:
|
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:
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.
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).
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).
Five attributes are required for creating a new user profile (see User Profile Fields for all attributes):
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.
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.
If the user.accountStatus has the value "Inactive", or user.employeeStatus has value "D", the user profile will be disabled.
<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> |
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <updateResponse xmlns="http://webservices.reardencommerce.com/userprofile/"> <responseCode xmlns="">OK</responseCode> <responseDataSet xmlns=""> <responseData> <companyId>84</companyId> <externalId>testuser</externalId> <externalIdSet/> </responseData> </responseDataSet> </updateResponse> </soapenv:Body> </soapenv:Envelope> |
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.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Header> <AuthHeader xmlns="http://webservices.reardencommerce.com/userprofile/"> <login>kentest</login> <password>MySharedSecret</password> <companyDomain>TestSite</companyDomain> </AuthHeader> </soapenv:Header> <soapenv:Body> <getPageRequest xmlns="http://webservices.reardencommerce.com/userprofile/"> <timestamp>2001-10-01T22:17:07.00</timestamp> </getPageRequest> </soapenv:Body> </soapenv:Envelope> |
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <getPageResponse xmlns="http://webservices.reardencommerce.com/userprofile/"> <customerSet xmlns=""> <user> <externalID>Z002J0KF</externalID> <domain>testcompany</domain> <accountStatus>Inactive</accountStatus> <employeeStatus>A</employeeStatus> <userInfo is-modified="true" last-updated="2014-10-05T05:42:01.000Z"> <accountType>0</accountType> <employeeID>121569</employeeID> <employeeType>VIP</employeeType> <userName>582064</userName> <firstName>Test1</firstName> <lastName>User1</lastName> <email>email1@deem.com</email> <costCenter>25025</costCenter> <departmentCode>RC-CA DF CS BA 2</departmentCode> <departmentName>S</departmentName> <businessUnit>SPD010</businessUnit> <jobLevel>1111</jobLevel> <jobTitle>SCICS</jobTitle> <division>SPD</division> <misField1>PCMYES</misField1> <misField2>ENG</misField2> <misField5>5</misField5> <workPhone> <number>5068551096</number> </workPhone> <groupwareID>email1@deem.com</groupwareID> <vipIndicator>false</vipIndicator> </userInfo> <customFieldSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"> <customFieldCollection> <name>addtlContact</name> <customField> <name>mgrEmail</name> <value>mgrEmail@deem.com</value> </customField> </customFieldCollection> </customFieldSet> <servicePreferences is-modified="true" last-updated="2014-10-05T05:42:01.000Z"> <airlinePreferences> <homeAirport/> <mealPreference/> <seatPreference/> <farePreference>-9</farePreference> </airlinePreferences> <carRentalPreferences> <defaultTransmissionType/> <defaultNumDoors/> <defaultCarType/> </carRentalPreferences> <defaultAirChargeCardNumber/> <defaultHotelChargeCardNumber/> <defaultCarChargeCardNumber/> </servicePreferences> <delegateSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <passportSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <nationalIDCardSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <visaSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <chargeCardSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <userCredentialsSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <userExternalIdSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"> <reardenPNRSyncID>402691</reardenPNRSyncID> <myProfileOrgID>0</myProfileOrgID> <myProfileTravelerID>0</myProfileTravelerID> </userExternalIdSet> <roleSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <timestamp>2014-10-05T05:42:01.000Z</timestamp> </user> <user> <externalID>Z0026XSF</externalID> <domain>testcompany</domain> <accountStatus>Inactive</accountStatus> <employeeStatus>A</employeeStatus> <userInfo is-modified="true" last-updated="2014-10-05T05:42:01.000Z"> <accountType>0</accountType> <employeeID>121211</employeeID> <employeeType>VIP</employeeType> <userName>581706</userName> <firstName>Test2</firstName> <lastName>User2</lastName> <email>email2@deem.com</email> <costCenter>51358</costCenter> <departmentCode>HC CX NAM CA DX MK</departmentCode> <departmentName>H</departmentName> <businessUnit>HDX024</businessUnit> <jobLevel>1111</jobLevel> <jobTitle>MSDBU</jobTitle> <division>HSC</division> <misField1>PCMYES</misField1> <misField2>ENG</misField2> <misField5>5</misField5> <workPhone> <number>4165289214</number> </workPhone> <groupwareID>email2@deem.com</groupwareID> <vipIndicator>false</vipIndicator> </userInfo> <customFieldSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"> <customFieldCollection> <name>addtlContact</name> <customField> <name>mgrEmail</name> <value>mgrEmail@deem.com</value> </customField> </customFieldCollection> </customFieldSet> <servicePreferences is-modified="true" last-updated="2014-10-05T05:42:01.000Z"> <airlinePreferences> <homeAirport/> <mealPreference/> <seatPreference/> <farePreference>-9</farePreference> </airlinePreferences> <carRentalPreferences> <defaultTransmissionType/> <defaultNumDoors/> <defaultCarType/> </carRentalPreferences> <defaultAirChargeCardNumber/> <defaultHotelChargeCardNumber/> <defaultCarChargeCardNumber/> </servicePreferences> <delegateSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <passportSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <nationalIDCardSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <visaSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <chargeCardSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <userCredentialsSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <userExternalIdSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"> <reardenPNRSyncID>402706</reardenPNRSyncID> <myProfileOrgID>0</myProfileOrgID> <myProfileTravelerID>0</myProfileTravelerID> </userExternalIdSet> <roleSet is-modified="true" last-updated="2014-10-05T05:42:01.000Z"/> <timestamp>2014-10-05T05:42:01.000Z</timestamp> </user> </customerSet> <recordsRemaining xmlns="">true</recordsRemaining> <conversationID xmlns="">17881</conversationID> </getPageResponse> </soapenv:Body> </soapenv:Envelope> |
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Header> <AuthHeader xmlns="http://webservices.reardencommerce.com/userprofile/"> <login>kentest</login> <password>MySharedSecret</password> <companyDomain>TestSite</companyDomain> </AuthHeader> </soapenv:Header> <soapenv:Body> <getPageRequest xmlns="http://webservices.reardencommerce.com/userprofile/"> <conversationID>17881</conversationID> <timestamp>2014-01-05T16:00:00.000</timestamp> </getPageRequest> </soapenv:Body> </soapenv:Envelope> |
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <getPageResponse xmlns="http://webservices.reardencommerce.com/userprofile/"> <customerSet xmlns=""/> <recordsRemaining xmlns="">false</recordsRemaining> <conversationID xmlns="">17881</conversationID> </getPageResponse> </soapenv:Body> </soapenv:Envelope> |