Profile Pull Web Service

Owned by IT Info
Last updated: Aug 18, 2023 by Malissa Olofernes
6 min read

As a site administrator, you can set up a site to retrieve profiles through the web service.

After clicking Web Services under the Settings tab, click Profile Pull Web Service. The Profile Pull Web Services page appears. You can set up the following activities for the site:

Adding or Editing a Subscription

Click Profile Pull Web Service Subscriptions to retrieve site profiles through the web service. Follow these steps:

  1. Add or edit a subscription:

    • To edit an existing subscription, click its name in the Subscription Name column, and the Edit Subscription page appears.

    • To add a new subscription, click the Add a New Subscription link. The Add Subscription page appears.

  2.  Enter information in the following fields or select the following choices, and then click Save:

Field or Selection

Description

General Settings: This section identifies who is pulling the data from Deem.

Subscription Name

Enter a name for the subscription.

Contact Name

Enter the contact name.

Contact Email

Enter the contact's email address.

Contact Phone

Enter the contact's phone number.

Web Service Type

This dropdown menu is currently set to User Profile.

Inbound Messages

Mode

Select one of the following from the dropdown menu:

  • Live

  • Test (the default)

The Test option lets you verify that the connection is working. The service can be tested during the development stage without affecting the database content at Deem. When ready, you can choose Live.

Test mode applies only if you are sending (aka "pushing") updates to Deem for this site. At least one of these options must be enabled: 

  • Allow update

  • Allow add

  • Allow delete/disable

If you are only retrieving (aka "pulling") records, you can change the Mode to Live.

If you select Test, the updates you send through the web service will not be reflected in the Deem database. If you select Live, all changes will be reflected in the database.

Inbound Message Unique Key

Note: This dropdown menu is relevant only when you are sending updates, adds, or deletes to Deem for the site. The partner must specifically identify in each record the user's unique identifier. Choose one of the following keys for profile retrieval:

  • User ID: This ID is internally generated by Deem.

  • User Name/Login: The user's login for the Deem system.

  • Email: The user' email.

  • External ID: Your company's external ID for the user.

  • Employee ID: The employee ID for the user.

Authentication

Username

Enter the username for authentication. The username must be a minimum of 8 characters, and include at least one letter and one number.

Password

Enter the user password. The password must be a minimum of 8 characters, and include at least one letter, one number, and one special character (# $ %, etc.).

Reenter Password

Re-enter the user password.

Permissions

Allow "read" of Deem
user profile

If you select this check box, user profiles are retrieved. This field enables retrieving the user profiles.

Allow "batch read" of
Deem user profiles 

If you select this check box, multiple user profiles are retrieved in a batch. This field enables retrieving user profiles in batch. Select a value from the "# of profiles to send per batch" field. 

This is the most efficient use of the web service. Typically this is set to 100, which is also the maximum number you can create.. 

# of profiles to send
per batch

This field defines how many profiles should be returned in one SOAP response message when retrieving the user profiles in batch. The maximum number that can be created is 100.

Allow "update" of existing
Deem user profiles 

Select this checkbox to allow user profile updates to be sent to Deem using the web service. 

Allow "add" of new Deem
user profiles if they
don't already exist 

Select this checkbox to allow user profile updates for users not currently in the system to be sent to Deem using the web service. The user will be added to the system, as long as the minimum number of required fields are present.

Allow "delete/disable" of
Deem user profiles 

Select this checkbox to enable sending a "deactivate" status in the web services update to deactivate a user in the system. 

Restrict "updates" to
match Profile Field Settings ("Profile Load" permissions)

If you select this checkbox, determine how updates sent using the web services are handled.  Each Web Services subscription has its own set of entries in the Profile Field Settings page. 

# of failed login attempts
before locking the account:

Select from the dropdown menu the number of unsuccessful attempts a user can make to log on before being locked out (2-10).

Lock for ___ minutes

Select from the dropdown menu the number of minutes a user should be locked out before being able to attempt to log on again (up to a half hour).

Creating a New User Profile

There are five required attributes for creating a new user profile: External ID, Username, Email, First Name, and Last Name. External ID is generated by the partner, and it needs to be unique to a user in a site. The username and email also need to be unique per user in a site.

Updating An Existing User Profile

When a user profile with a given external ID already exists, the existing profile will be updated with new profile information, if the user.timestamp in the request (should be provided in GMT) is later than the last time the profile was updated in Rearden's system. If it’s not, the profile update will be rejected.

To clear the child element's value for the “user,” a string value of 'NULL' must be provided. There are exceptions for child elements. Birthdays, titles, and vipIndicators will clear the value even if left empty or excluded. To clear an address, provide an address element with empty child elements.

Collection types such as preferences, visas, passports, national ID cards, charge cards, if provided, need to be provided with a full list of items. If an existing item is not provided in the collection, it will be deleted. 

Starting Release 2017.1.1, update request will delete entire collection set listed below from profile. Below are xml tags for supported sets:

attribute mode = "delete" will delete entire collection set values.

  1. <delegateSet mode="delete"/>

  2. <chargeCardSet mode="delete"/>

  3. <passportSet mode="delete"/>

  4. <nationalIDCardSet mode="delete"/>

  5. <userCredentialsSet mode="delete"/>

  6. <passportSet mode="delete"/>

  7. <roleSet  mode="delete"/>

  8. servicePreferences – > airlinePreferences – > <airSpecialRequestSet  mode="delete"/>

  9. servicePreferences – > hotelPreferences – > <hotelSpecialRequestSet  mode="delete"/>

  10. servicePreferences – > hotelPreferences – > <preferredHotelAmenitySet  mode="delete"/>

  11. servicePreferences – > carRentalPreferences – > <carSpecialRequestSet  mode="delete"/>

  12. servicePreferences – > airlinePreferences --> <membershipSet  mode="delete"/>

  13. servicePreferences – > hotelPreferences – > <membershipSet mode="delete"/>

  14. servicePreferences – > carRentalPreferences–> <membershipSet mode="delete"/>

  15. servicePreferences – > railPreferences–> <membershipSet mode="delete"/>

  16. customField

For customFieldSet, delete mode works on tags as shown below. Delete flag will only delete values for specific fields. Therefore. in the below example, 1234567 will be deleted.

As customField are shared across domain users, a user cannot delete the field, as only value deletion is permitted.

<customFieldSet>
<customFieldCollection>
<name>testCollection1</name>
<customField mode="delete">
<name>testField1</name>
<value>1234567</value>
</customField> 
</customFieldCollection>
</customFieldSet>

Disabling An Existing User Profile

When user.accountStatus has a value ‘Inactive' or user.employeeStatus has a value 'D,’ the user profile will be disabled.

Note for Request and Response

When the request has multiple user profiles, they will be created or updated as best as they can. If all the profiles are processed without any error, response message will have responseCode 'OK.' ResponseDataSet will have a list of elements with companyID, externalID, and externalIDSet.

If any profile is rejected or fails to process, the response code will be 'PROBLEM,' and it will say rejectedCustomerSet and/or failedProfileSet. RejectedCustomerSet will be returned with full 'user' element(s). FailedPorfileSet will have failedProfile with externalID and errorMessage.

Managing Sets of Web Service Subscriptions

You can manage sets of web service subscriptions and assign them to groups of users. To create a subscription set, you first need to create at least one subscription – see "Adding or Editing a Subscription" in this topic.

Note: For details on using groups, see Groups Tab for Managing Groups.

Click Profile Pull Web Service Subscription Sets to manage sets of web service subscriptions to assign to groups. The Subscription Sets page appears.

To add or edit an existing set, follow these steps:

  1. Click the set name in the Set Name column to edit a set, or the Add a New Subscription Set link to add a set. The Edit Subscription Set or Add Subscription Set page appears.

  2. If you are adding a set, enter the name in the Set Name field.

  3. To add a subscription:

    1. Click Add Subscr. The Search & Add Code to Set page appears. 

    2. Select a subscription from the list and click OK, or click OK & Add Another and repeat the above step. 

  4. Click Save to save your set and return to the Subscription Sets page.

  5. Click Done.

Manually Testing Requests

Click Test Profile Pull Web Service to manually test web service requests. The Test Profile Pull Web Service page appears with Request and Response text fields.

Note: If the Mode for the subscription's log in and password is set to Live mode (see "Adding or Editing a Subscription" in this topic), then the Request messages may cause real updates to the service. Set the subscription to Test mode to ensure that no data is actually changed by these queries.

To test the web service request, perform the following steps:

  1. Enter a sample request XML message in the Request field. The following is an example message:
    Note: Use the below example as a starting point to create your own message. In the example provided, replace the login field and password field with a valid subscription log in and password.
     <getRequest>
    <authentication><login>PARTNER-LOGIN</login><password>PARTNER-PASSWORD</password>
    <companyDomain>talaris</companyDomain></authentication>
    <uniqueID>21701</uniqueID>
    </getRequest>

  2.  Click Submit Request. The XML response will appear in the Response field. To view the XML output in a easier format, copy the contents in the Response field and paste it into a text or word processing program. Save the file with the extension ".xml".

  3. Locate the ".xml" file on your hard drive, and then double-click the file to open it.

Downloading Documentation

Click Documentation to download the Web Services Description Language (WSDL) and XML Schema Definition (XSD) files for the user profile.