Synchronize person service

The synchronize person service is an inbound web service responsible for adding or updating a person in HCL Commerce to synchronize HCL Commerce with the external master repository.

Typical use cases

  • Creating or updating a person
  • Creating or updating an address for a person

Endpoint URL and operation

The default endpoint URL of this inbound web service is https://hostname:8000/webapp/wcs/services/MemberServices. The operation of this inbound web service is SyncPerson, with the SyncPerson BOD as request and the ConfirmBOD BOD as response.

Request

Requests to this inbound web service are in the form of SyncPerson BODs. There are two types of requests that can be made:

  1. Add or update a person
  2. Add or update an address for a person

Adding or updating a person

Requests to add or update a person is mapped to com.ibm.commerce.usermanagement.commands.UserRegistrationAdminUpdateCmd and should contain the following information:

XPath* Type Maps to the following command parameter Description Required
ApplicationArea/BusinessContext/ContextData USERDATA-Context Data. For example:
  • storeId
  • langId
N
DataArea/Sync/ActionCriteria/ActionExpression/@actionCode stringactionThe action code. Valid values are as follows: Add: to add a person.

Change: to update an existing person.

Y
DataArea/Sync/ActionCriteria/ActionExpression stringcommerceObject Action Expression. Must be specified as follows:
  • Person
Y
DataArea/Person/ParentIdentifier/DistinguishedName stringparentMember Distinguished name of the parent organization. If unspecified, the default values are: o=default organization, o=root organization N
DataArea/Person/Authentication/LogonID stringlogonIdLog on ID of the person.Y
DataArea/Person/Authentication/Password stringlogonPassword Password of the person.Y - when you add a person

N - when you update a person

DataArea/Person/Authentication/SecurityHint/Question stringchallengeQuestion Challenge question to confirm the identity of a person. N
DataArea/Person/Authentication/SecurityHint/Answer stringchallengeAnswer Answer to the challenge question.N
DataArea/Person/Authentication/@expired booleanpasswordExpired Specifies whether the user password expired. Valid values are as follows:
  • true (expired)
  • false (not expired)
N
DataArea/Person/Authentication/@status booleanuserStatus Allows the person to have the logon ID disabled without removing the person from the system.
  • true (enabled)
  • false (disabled)
N
DataArea/Person/Authentication/UserData/UserDataField USERDATA-Used to pass more parameters to the target command.N
DataArea/Person/PersonName/LastName stringlastNameLast nameN
DataArea/Person/PersonName/PersonTitle stringpersonTitle Title of the person, for example, Dr., Mr. or Ms.N
DataArea/Person/PersonName/FirstName stringfirstName First name of the personN
DataArea/Person/PersonName/MiddleName stringmiddleName Middle name of the personN
DataArea/Person/PersonalProfile/PreferredCurrency stringpreferredCurrency The person's preferred currency. A foreign key that references the SETCCURR column of the SETCURR table.N
DataArea/Person/PersonalProfile/PreferredLanguage stringpreferredLanguage The person's preferred language; a foreign key that references the LANGUAGE_ID column of the LANGUAGE table.N
DataArea/Person/PersonalProfile/DisplayName stringdisplayName Name that is used to display the name of the person in a summary list.N
DataArea/Person/PersonalProfile/PhotoURL stringphotoA location for the photograph of the person.N
DataArea/Person/PersonalProfile/PreferredMeasure stringpreferredMeasure The preferred unit of measure.N
DataArea/Person/PersonalProfile/PreferredCommunication stringpreferredCommunication Preferred method of communication by phone.N
DataArea/Person/PersonalProfile/PreferredDelivery stringpreferredDelivery Preferred delivery method.N
DataArea/Person/PersonalProfile/Description stringdescription Description of the person.N
DataArea/Person/PersonalProfile/Gender stringgenderThe gender of the person. Valid values are as follows:
  • F: female
  • M: male
  • N: not provided
If not provided, N is used as the default.
N
DataArea/Person/PersonalProfile/Income intincomeThe annual income for the person.N
DataArea/Person/PersonalProfile/MaritalStatus stringmaritalStatus The marital status of the person.N
DataArea/Person/PersonalProfile/IncomeCurrency stringincomeCurrency Currency for the income of the person.N
DataArea/Person/PersonalProfile/NumberOfChildren intchildrenThe number of children that the person has. If not provided, the default is 0.N
DataArea/Person/PersonalProfile/Household inthouseholdNumber of people in the household.N
DataArea/Person/PersonalProfile/CompanyName stringcompanyName The company for which the person works.N
DataArea/Person/PersonalProfile/Hobbies stringhobbiesThe main interests and hobbies of the person.N
DataArea/Person/PersonalProfile/Timezone stringtimeZoneThe time zone in which the person resides.N
DataArea/Person/PersonalProfile/UserData/UserDataField USERDATA-Used to pass more parameters to the target command.N
DataArea/Person/BusinessProfile/BusinessTitle stringbusinessTitle The business title.N
DataArea/Person/BusinessProfile/OrganizationName stringorganizationName The name of the organization.N
DataArea/Person/BusinessProfile/OrganizationalUnitName stringorganizationUnitName Name of the organizational unit.N
DataArea/Person/BusinessProfile/EmployeeID stringemployeeId A method to identify the employee, such as by employee number. N
DataArea/Person/BusinessProfile/AlternateID stringalternateId A special ID assigned by the organization or organizational unit to which this business user belongs.N
DataArea/Person/BusinessProfile/EmployeeType stringemployeeType The employee type, such as regular, part time, special part time, supplemental, and contractor.N
DataArea/Person/BusinessProfile/DepartmentNumber stringdepartmentNumber The department number for the business user.N
DataArea/Person/BusinessProfile/Manager stringmanagerThe name of the manager or supervisor of this business user.N
DataArea/Person/BusinessProfile/Secretary stringsecretary The name of the secretary or administrative assistant of the business user.N
DataArea/Person/BusinessProfile/RequisitionerID stringrequisitionerId A unique ID for identifying the requisitioner.N
DataArea/Person/BusinessProfile/UserData/UserDataField USERDATA-Used to pass more parameters to the target command.N
DataArea/Person/ContactInfo/Telephone[1] stringphone1The person's primary phone number.N
DataArea/Person/ContactInfo/Telephone[1]/@type stringphone1Type The type of phone that is used for the primary phone number. For example, tty for hearing impaired, PCM for pulse-coded modulation, or CEL for mobile. This value is a field of 3 characters.N
DataArea/Person/ContactInfo/Telephone[1]/@publish booleanpublishPhone1 Specifies whether the primary phone number is listed. N
DataArea/Person/ContactInfo/Telephone[2] stringphone2The person's secondary phone number.N
DataArea/Person/ContactInfo/Telephone[2]/@type stringphone2Type The type of phone that is used for the secondary phone number. For example, tty for hearing impaired, PCM for pulse-coded modulation, or CEL for mobile. This value is a field of 3 characters.N
DataArea/Person/ContactInfo/Telephone[2]/@publish booleanpublishPhone2 Specifies whether the primary phone number is listed. N
DataArea/Person/ContactInfo/Email[1] stringemail1The person's primary email address.N
DataArea/Person/ContactInfo/Email[2] stringemail2The person's secondary email address.N
DataArea/Person/ContactInfo/Fax[1] stringfax1The person's primary fax number.N
DataArea/Person/ContactInfo/Fax[2] stringfax2The person's secondary fax number.N
DataArea/Person/ContactInfo/Address/@type stringaddressType The purpose of the address. Valid values are:
  • S: shipping
  • B: billing
  • SB: shipping and billing (The default value)
N
DataArea/Person/ContactInfo/Address/City stringcityThe city.N
DataArea/Person/ContactInfo/Address/StateOrProvinceName stringstateThe state or province.N
DataArea/Person/ContactInfo/Address/Country stringcountryThe country or region.N
DataArea/Person/ContactInfo/Address/PostalCode stringzipCodeThe zip code or postal code.N
DataArea/Person/ContactInfo/Address/AddressLine[1] stringaddress1The first line of the street address.N
DataArea/Person/ContactInfo/Address/AddressLine[2] stringaddress2The second line of the street address.N
DataArea/Person/ContactInfo/Address/AddressLine[3] stringaddress3The third line of the street address.N
DataArea/Person/ContactInfo/Address/UserData/UserDataField USERDATA-Used to pass more parameters to the target command.N
DataArea/Person/ContactInfo/UserData/UserDataField USERDATA-Used to pass more parameters to the target command.N
DataArea/Person/ContextAttribute[j]/Name string attributeName portion of the following custom member attribute specification: &attributeName_storeId_r_n=value Name of a customizable attribute.N
DataArea/Person/ContextAttribute[j]/AttributeValue[k]/Value[n] string value portion of the following custom member attribute specification: &attributeName_storeId_r_n=value Value of the customizable attribute.N
DataArea/Person/ContextAttribute[j]/AttributeValue[k]/StoreID int storeId portion of the following custom member attribute specification: &attributeName_storeId_r_n=value Store ID where the attribute value applies. If not specified, the value applies to all stores.N
DataArea/Person/UserData/UserDataField USERDATA-Used to pass more parameters to the target command.N

Adding or updating an address for a person:

Requests to add or update an address for a person is mapped to com.ibm.commerce.usermanagement.commands.AddressAddCmd and com.ibm.commerce.usermanagement.commands.AddressUpdateCmd. The requests should contain the following information:

XPath* TypeMaps to the following command parameter DescriptionRequired
ApplicationArea/BusinessContext/ContextData USERDATA-Context Data. For example:
  • storeId
  • langId
N
DataArea/Sync/ActionCriteria/ActionExpression/@actionCode stringactionThe action code. Valid values are as follows:
  • Add: to add an address for a person
  • Change: to update an address for a person
Y
DataArea/Sync/ActionCriteria/ActionExpression stringcommerceObject Action Expression. Must be specified as follows:
  • Person/ContactList/ContactEntry
Y
DataArea/Person/PersonIdentifier/DistinguishedName stringdistinguishedName Distinguished name of the person, used along with the nickname to identify the person.Y
DataArea/Person/ContactList/ContactEntry/@contactNickName stringnickNameThe nickname or identifier of the address that is being added. A person can have a collection of addresses, each with a nickname. The address that a user provides during registration is treated by the system as the person's own address. The system sets the nickname of that address to the person's logon ID.Y
DataArea/Person/ContactList/ContactEntry/ContactName/LastName stringlastNameSurname of the person.N
DataArea/Person/ContactList/ContactEntry/ContactName/PersonTitle stringpersonTitle Title of the person, for example, Dr., Mr. or Ms.N
DataArea/Person/ContactList/ContactEntry/ContactName/FirstName stringfirstName Given name of the person.N
DataArea/Person/ContactList/ContactEntry/ContactName/MiddleName stringmiddleName Middle name of the person.N
DataArea/Person/ContactList/ContactEntry/Telephone[1] stringphone1The person's primary phone number.N
DataArea/Person/ContactList/ContactEntry/Telephone[1]/@type stringphone1Type The type of phone that is used for the primary phone number. For example, tty for hearing impaired, PCM for pulse-coded modulation, or CEL for mobile. This value is a field of 3 characters.N
DataArea/Person/ContactList/ContactEntry/Telephone[1]/@publish stringpublishPhone1 Specifies whether the primary phone number is listed. N
DataArea/Person/ContactList/ContactEntry/Telephone[2] stringphone2The person's secondary phone number.N
DataArea/Person/ContactList/ContactEntry/Telephone[2]/@type stringphone2Type The type of phone that is used for the secondary phone number. For example, tty for hearing impaired, PCM for pulse-coded modulation, or CEL for mobile. This value is a field of 3 characters.N
DataArea/Person/ContactList/ContactEntry/Telephone[2]/@publish stringpublishPhone2 Specifies whether the primary phone number is listed. N
DataArea/Person/ContactList/ContactEntry/Email[1] stringemail1The person's primary email address.N
DataArea/Person/ContactList/ContactEntry/Email[2] stringemail2The person's secondary email address.N
DataArea/Person/ContactList/ContactEntry/Fax[1] stringfax1The person's primary fax number.N
DataArea/Person/ContactList/ContactEntry/Fax[2] stringfax2The person's secondary fax number.N
DataArea/Person/ContactList/ContactEntry/Address/@type stringaddressType The purpose of the address. Valid values are:
  • S: shipping
  • B: billing
  • SB: shipping and billing (The default value)
N
DataArea/Person/ContactList/ContactEntry/Address/City stringcityThe city.N
DataArea/Person/ContactList/ContactEntry/Address/StateOrProvinceName stringstateThe state or province.N
DataArea/Person/ContactList/ContactEntry/Address/Country stringcountryThe country or region.N
DataArea/Person/ContactList/ContactEntry/Address/PostalCode stringzipCodeThe zip code or postal code.N
DataArea/Person/ContactList/ContactEntry/Address/AddressLine[1] stringaddress1The first line of the street address.N
DataArea/Person/ContactList/ContactEntry/Address/AddressLine[2] stringaddress2The second line of the street address.N
DataArea/Person/ContactList/ContactEntry/Address/AddressLine[3] stringaddress3The third line of the street address.N
DataArea/Person/ContactList/ContactEntry/Address/UserData/UserDataField USERDATA-Used to pass more parameters to the target command.N
DataArea/Person/ContactList/ContactEntry/UserData/UserDataField USERDATA-Used to pass more parameters to the target command.N

* Namespace prefixes that are ignored for simplicity.

Examples

Response

Responses of this inbound web service are in the form of ConfirmBOD BODs.

A response to adding or updating a person contains the following information:

XPath* Type Description
DataArea/BOD/BODSuccessMessage -This element is present if the request was successful.
DataArea/BOD/BODSuccessMessage/UserArea/Person/PersonIdentifier/UniqueID stringMember ID of the person

A response to adding or updating a person's address contains the following information:

XPath* Type Description
DataArea/BOD/BODSuccessMessage -This element is present if the request was successful.

* Namespace prefixes are ignored for simplicity.

Examples

Exceptions

All exceptions are returned in the form of ConfirmBOD BODs with a ResponseCriteria element under the Confirm verb. The elements contain the following information:

XPath* Type Description
DataArea/Confirm/ResponseCriteria/ChangeStatus/Code stringThe correlation identifier. Can be used to uniquely identify an exception in the server logs.
DataArea/Confirm/ResponseCriteria/ChangeStatus/ReasonCode stringThe reason code, which is either a HCL Commerce system error code code if available, or the EC message key plus an optional secondary error code if the HCL Commerce system error code is unavailable (usually in the case of application exceptions).
DataArea/Confirm/ResponseCriteria/ChangeStatus/Reason stringThe exception message.

* Namespace prefixes are ignored for simplicity.

Message mapping file used: SyncPersonBODMapping.xml

Examples