Profile Web Service Subscription (High level Technical)

Deem offers the User Profile web service, designed for partners and third-party application providers to manage user profiles efficiently. This service allows you to create, update, disable, or retrieve user profiles, which are collections of personal data linked to individual users. The User Profile web service delivers the essential user data needed for various transactions and interactions within services.

Proper management and security of profile data are crucial for maintaining data integrity and privacy. This document provides a comprehensive technical specification to guide partners in accessing and utilizing the User Profile web service from their web service clients.

1 Need to Know
2 Configuring Web Service Subscription (WSS) at the Site Level
3 Update/Confirm Web Service Subscription Set:
4 Update Confirm Web Services Rules:
5 Advanced Technical Resources

Need to Know

The User Profile web service utilizes Extensible Markup Language (XML) messages and adheres to the Simple Object Access Protocol (SOAP) standard, which facilitates the exchange of structured information.
Partners and application providers can develop web service clients to interact with the User Profile web service using the Web Service Definition Language (WSDL) file and schema provided in this document. WSDL is an XML format that describes network services by defining endpoints, expected parameters, and data structures in a machine-readable format.
With the User Profile web service, web service clients can retrieve and update user profile information. Clients must specify the desired profile details in each request to minimize latency and avoid the performance overhead of multiple API calls. User identification is managed through an ID (externalID) provided during single sign-on (SSO) via Security Assertion Markup Language (SAML) identity assertion.
or technical specifications related to session management and SSO integration, refer to Implementing Single Sign-On (SSO) for Desktop.
To configure this subscription at the super-domain level for multiple sites, submit a Deem Support case to receive the instructions for configuring the web service at the super-domain.
The following instructions pertain to site-level configuration. Settings configured in your template site will automatically apply to any new sites created from that template.

Configuring Web Service Subscription (WSS) at the Site Level

To configure Web Services for a single site, you must add the subscription to a subscription set and associate this set with a user group using a web service rule. Follow these steps:

Create/Update Web Services Subscription (WSS):

Navigate to the partner dashboard home page and select Settings link corresponding to the site you want to modify.
Go to the Settings tab and select Web Services.

Select Profile Pull Web Service.

Select Profile Pull Web Service Subscriptions.

If an existing subscription is available, select it, otherwise click Add A New Subscription to create a new subscription.

Update General Settings:

Subscription Name: Enter the name for the subscription.
Contact Name: Enter the TMC contact name.
Contact Email: Enter the TMC contact email.
Contact Phone: Enter the TMC contact phone number.
Web Service Type: Select User Profile.

Update Inbound Messages:

Mode: Select Live.
Inbound Message Unique Key: Select User Name / Login.
Username: Enter 8-12 character alphanumeric username.
Password: Enter an 8-12 character password, excluding ambiguous characters (e.g., &, <).

Note: Use a secure password generator to create these credentials. Example services include:

Update Permissions: Depending on whether Deem is your master profile system, customers will have the option to update their profile either within Deem or through a third-party system.

If Deem is the Master Profile: The profile management tool will pull any profile updates/changes and additions from Deem to their system and push to the GDS. Configure two WSSs:
One for PUSH/ADD/UPDATE (refer to the 2nd screenshot).
One for PULL/CHANGES/DEACTIVATED (refer to the 3rd screenshot).

If Deem is NOT the Master Profile System: The external profile system will push data into Deem and the GDS. All updates are managed by the external profile tool, which will synchronize data with both Deem and the GDS.

Click Save to finalize the changes.

Update/Confirm Web Service Subscription Set:

Click the Back to Profile Pull Web Services link at the top of the page.
Select Profile Pull Web Service Subscription Sets link.

Select existing subscription set or Click Add A New Subscription Set to create a new set.

If creating a new set, enter Set Name.
Select Add Subscr.

Click the radio button next to the name of the subscription you want to add, then click OK to add multiple subscriptions, select Ok & Add Another.

Click Save to finalize the changes.

Update Confirm Web Services Rules:

Navigate to the Rules tab.
Select Web Services Rules link.

Choose Edit or Add to either verify that the correct Web Service Subscription is applied and activated for the group or to add and activate a new Web Service Subscription.

The Add link indicates that no web services are currently established for the group.
The Edit link in green indicates that web services are established for the group and are active.
The Edit link in yellow indicates that web services are established for the group but are inactive.

Optionally, enter a Description for the rule that is easily recognizable.
Check box next to Activate Rule.
Check box next to Enable Web Services using the following configuration sets.
Select the desired Web Service Subscription from the list.
Click Save.

Click Save Priority Changes.

Click the changes not applied link in the top right corner of the page, to finalize all changes.

Test the configuration to ensure it operates as expected.

Advanced Technical Resources

As a partner, you can create a web service client to access the User Profile web service using the provided Web Service Definition Language (WSDL) file, User Profile Schema file, and Common Types Schema file. Follow these steps to download these files:

Navigate to the partner dashboard home page and click the Settings link for the site you wish to modify.

On the Settings tab, select the Web Services link.

Click the Profile Pull Web Service link at the top of the page to access the Profile Pull Web Services page.

Click the Documentation link to download the WSDL file, User Profile Schema file, and Common Types Schema file.

Additionally, we provide the profile attributes in the User Profile Fields section and a list of pre-defined values for these attributes in the Profile List of Values section.

The following examples illustrate sample request and response SOAP messages. The Web Service client can include multiple user elements in the customerSet, up to the maximum number of profiles allowed per batch as specified in the web services subscription.

Successful Processing: If a request contains multiple user profiles, each profile will be created or updated. If all profiles are processed successfully without errors, the response message will include a responseCode of "OK". The ResponseDataSet will contain elements such as companyID, externalID, and externalIDSet.

Error Handling: If any profile is rejected or fails to be processed, the responseCode will be set to "PROBLEM". The response will include:

rejectedCustomerSet with the full user elements for profiles that were rejected.

failedProfileSet with details of failed profiles, including 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 responsible for configuring domain or super-domain web service subscriptions, enabling the web service rules, and providing partners with the necessary authentication credentials. To facilitate testing against Deem's QA environment, the Integration Team will provide an externally accessible QA environment along with the 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, update, disable, or retrieve user profiles. The attributes for a user profile are detailed in the User Profile Fields, section, while fixed values for certain attributes are listed in the Profile List of Values.

Note: For all profile creation, update, and disablement operations, the same updateRequest element is used in the request body (refer to the sample SOAP request for details).

Creating a New User Profile

Five attributes are required to create a new user profile. For a complete list of all required and optional attributes, refer to the User Profile Fields section.

external ID

username

email

first name

last name

The external ID (externalID) is generated by the partner and must uniquely identify each user within a site. Additionally, both the username and email must be unique for each user.

Updating an Existing User Profile

If a user profile with a given externalID already exists, it can be updated with new information from a request message if the user.timestamp in the request (in GMT format) is later than the profile's last modified time in the system. If the timestamp is not later, the profile update will be rejected.

To clear the value of a child element in the user profile, include a string value of "NULL". Exceptions are:

For birthDay, title, and vipIndicator, an empty value or the exclusion of the element will clear the value.

To clear an address, provide an address element with empty child elements.

For collection types such as preferences, visas, passports, national ID cards, and charge cards, if included, you must provide the full list of items. Any existing items not included in the collection will be deleted.

Note: The accountStatus field is used only for clients utilizing Single Sign-On (SSO), where no activation email is required, and authentication is managed by the identity provider. For SSO clients, set accountStatus to “A” to grant immediate access. If SSO is not used, leave accountStatus blank and use employeeStatus instead.

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">

<user>

<externalID>testuser</externalID>

<domain>testcompany</domain>

<accountStatus>Active</accountStatus>

<userName>testuser</userName>

<jobTitle>engineer</jobTitle>

</workPhone>

</mobilePhone>

<companyName>testcompany</companyName>

<street1>22 test street</street1>

</address>

<emergencyContactName>Mrs. Smith</emergencyContactName>

<emergencyContactRelationship>Spouse/Domestic Partner</emergencyContactRelationship>

</emergencyContactPrimaryPhone>

</userInfo>

<seatPreference>Aisle</seatPreference>

</airlinePreferences>

</carRentalPreferences>

</servicePreferences>

</passport>

</passportSet>

<cardName>My Master Card</cardName>

<street1>123 main street</street1>

</billingAddress>

</chargeCard>

</chargeCardSet>

</user>

</customerSet

</updateRequest>

</s:Body>

</s:Envelope>

Sample Update Response SOAP Message

<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>

<externalId>testuser</externalId>

</responseData>

</responseDataSet>

</updateResponse>

</soapenv:Body>

</soapenv:Envelope>

Retrieving a Batch of User Profiles

To retrieve user profile data, send a getPageRequest. When sending this request for the first time, you must specify a timestamp. This timestamp ensures that only profiles modified after the specified date and time are returned. The response will include a batch of user profiles, with the number of profiles limited to the maximum configured for your subscription (default is 100).

Additionally, the response will include two important metadata fields at the bottom:

recordsRemaining: Indicates whether there are additional profiles available for retrieval 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 more 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 receiving a conversationID from your initial response, continue to use that conversationID in all subsequent requests to prevent retrieving duplicate profiles. Avoid establishing a new conversationID.

Tip: If a response indicates "false" for the recordsRemaining field, you can still make additional requests using the same conversationID to check for updates to previously retrieved profiles. This is useful for retrieving any updated profiles as they become available.

Sample Initial Get Request SOAP Message

<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>

<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>

Sample Initial Get Response SOAP Message

<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>

<user>

<domain>testcompany</domain>

<accountStatus>Inactive</accountStatus>

<email>email1@deem.com</email>

<jobTitle>SCICS</jobTitle>

<misField1>PCMYES</misField1>

</workPhone>

<groupwareID>email1@deem.com</groupwareID>

<vipIndicator>false</vipIndicator>

</userInfo>

<name>addtlContact</name>

<name>mgrEmail</name>

<value>mgrEmail@deem.com</value>

</customField>

</customFieldCollection>

</customFieldSet>

</airlinePreferences>

</carRentalPreferences>

</servicePreferences>

</userExternalIdSet>

</user>

<user>

<domain>testcompany</domain>

<accountStatus>Inactive</accountStatus>

<email>email2@deem.com</email>

<jobTitle>MSDBU</jobTitle>

<misField1>PCMYES</misField1>

</workPhone>

<groupwareID>email2@deem.com</groupwareID>

<vipIndicator>false</vipIndicator>

</userInfo>

<name>addtlContact</name>

<name>mgrEmail</name>

<value>mgrEmail@deem.com</value>

</customField>

</customFieldCollection>

</customFieldSet>

</airlinePreferences>

</carRentalPreferences>

</servicePreferences>

</userExternalIdSet>

</user>

</customerSet>

</getPageResponse>

</soapenv:Body></soapenv:Envelope>

Sample Subsequent Get Request SOAP Message

<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>

<login>kentest</login>

<password>MySharedSecret</password>

<companyDomain>TestSite</companyDomain>

</AuthHeader>

</soapenv:Header>

<soapenv:Body> <getPageRequest xmlns="http://webservices.reardencommerce.com/userprofile/">

</getPageRequest>

</soapenv:Body>

</soapenv:Envelope>

Sample Subsequent Get Request SOAP Message

<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>

<recordsRemaining xmlns="">false</recordsRemaining>

</getPageResponse>

</soapenv:Body>

</soapenv:Envelope>