Develop > Persistence layer > WebSphere Commerce Web services with JSP pages > Understand the WebSphere Commerce Web service framework > WebSphere Commerce as a service provider > Inbound Web services provided


Synchronize person service

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


Typical use cases


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


Add or updating a person

Requests to add or update a person will be 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 string action The action code. Valid values are... Add: to add a person Change: to update an existing person Y
DataArea/Sync/ActionCriteria/ActionExpression string commerceObject Action Expression. Must be specified...

  • Person

Y
DataArea/Person/ParentIdentifier/DistinguishedName string parentMember Distinguished name of the parent organization. If unspecified, default is the following: o=default organization, o=root organization N
DataArea/Person/Authentication/LogonID string logonId Logon ID of the person. Y
DataArea/Person/Authentication/Password string logonPassword Password of the person. Y - when adding a personN - when updating a person
DataArea/Person/Authentication/SecurityHint/Question string challengeQuestion Challenge question to confirm a person's identity. N
DataArea/Person/Authentication/SecurityHint/Answer string challengeAnswer Answer to the challenge question. N
DataArea/Person/Authentication/@expired boolean passwordExpired Specifies whether the user password has expired. Valid values are...

  • true (expired)

  • false (not expired)

N
DataArea/Person/Authentication/@status boolean userStatus 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 additional parameters to the target command. N
DataArea/Person/PersonName/LastName string lastName Last name N
DataArea/Person/PersonName/PersonTitle string personTitle Title of the person, for example, Dr., Mr. or Ms. N
DataArea/Person/PersonName/FirstName string firstName First name of the person N
DataArea/Person/PersonName/MiddleName string middleName Last name of the person N
DataArea/Person/PersonalProfile/PreferredCurrency string preferredCurrency The person's preferred currency. A foreign key that references the SETCCURR column of the SETCURR table. N
DataArea/Person/PersonalProfile/PreferredLanguage string preferredLanguage The person's preferred language; a foreign key that references the LANGUAGE_ID column of the LANGUAGE table. N
DataArea/Person/PersonalProfile/DisplayName string displayName Name used when displaying the name of the person in a summary list. N
DataArea/Person/PersonalProfile/PhotoURL string photo A location for the photograph of the person. N
DataArea/Person/PersonalProfile/PreferredMeasure string preferredMeasure The preferred unit of measure. N
DataArea/Person/PersonalProfile/PreferredCommunication string preferredCommunication Preferred method of communication by phone. N
DataArea/Person/PersonalProfile/PreferredDelivery string preferredDelivery Preferred delivery method. N
DataArea/Person/PersonalProfile/Description string description Description of the person. N
DataArea/Person/PersonalProfile/Gender string gender The gender of the person. Valid values are...

  • F: female

  • M: male

  • N: not provided

If not provided, N is used as the default.

N
DataArea/Person/PersonalProfile/Income int income The annual income for the person. N
DataArea/Person/PersonalProfile/MaritalStatus string maritalStatus The marital status of the person. N
DataArea/Person/PersonalProfile/IncomeCurrency string incomeCurrency Currency for the income of the person. N
DataArea/Person/PersonalProfile/NumberOfChildren int children The number of children that the person has. If not provided, the default is 0. N
DataArea/Person/PersonalProfile/Household int household Number of people in the household. N
DataArea/Person/PersonalProfile/CompanyName string companyName The company for which the person works. N
DataArea/Person/PersonalProfile/Hobbies string hobbies The main interests and hobbies of the person. N
DataArea/Person/PersonalProfile/Timezone string timeZone The time zone in which the person resides. N
DataArea/Person/PersonalProfile/UserData/UserDataField USERDATA - Used to pass additional parameters to the target command. N
DataArea/Person/BusinessProfile/BusinessTitle string businessTitle The business title. N
DataArea/Person/BusinessProfile/OrganizationName string organizationName The name of the organization. N
DataArea/Person/BusinessProfile/OrganizationalUnitName string organizationUnitName Name of the organizational unit. N
DataArea/Person/BusinessProfile/EmployeeID string employeeId A method to identify the employee, such as by employee number. N
DataArea/Person/BusinessProfile/AlternateID string alternateId A special ID assigned by the organization or organizational unit to which this business user belongs. N
DataArea/Person/BusinessProfile/EmployeeType string employeeType The employee type, such as regular, part time, special part time, supplemental, and contractor. N
DataArea/Person/BusinessProfile/DepartmentNumber string departmentNumber The department number for the business user. N
DataArea/Person/BusinessProfile/Manager string manager The name of the manager or supervisor or this his business user. N
DataArea/Person/BusinessProfile/Secretary string secretary The name of the secretary or administrative assistant of the business user. N
DataArea/Person/BusinessProfile/RequisitionerID string requisitionerId A unique ID for identifying the requisitioner. N
DataArea/Person/BusinessProfile/UserData/UserDataField USERDATA - Used to pass additional parameters to the target command. N
DataArea/Person/ContactInfo/Telephone[1] string phone1 The person's primary phone number. N
DataArea/Person/ContactInfo/Telephone[1]/@type string phone1Type The type of phone used for the person's primary phone number, for example TTY for hearing impaired, PCM for pulse-coded modulation, or CEL for mobile. This is a field of 3 characters. N
DataArea/Person/ContactInfo/Telephone[1]/@publish boolean publishPhone1 Specifies whether the primary phone number is listed. N
DataArea/Person/ContactInfo/Telephone[2] string phone2 The person's secondary phone number. N
DataArea/Person/ContactInfo/Telephone[2]/@type string phone2Type The type of phone used for the person's secondary phone number, for example TTY for hearing impaired, PCM for pulse-coded modulation, or CEL for mobile. This is a field of 3 characters. N
DataArea/Person/ContactInfo/Telephone[2]/@publish boolean publishPhone2 Specifies whether the primary phone number is listed. N
DataArea/Person/ContactInfo/Email[1] string email1 The person's primary email address. N
DataArea/Person/ContactInfo/Email[2] string email2 The person's secondary email address. N
DataArea/Person/ContactInfo/Fax[1] string fax1 The person's primary fax number. N
DataArea/Person/ContactInfo/Fax[2] string fax2 The person's secondary fax number. N
DataArea/Person/ContactInfo/Address/@type string addressType 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 string city The city. N
DataArea/Person/ContactInfo/Address/StateOrProvinceName string state The state or province. N
DataArea/Person/ContactInfo/Address/Country string country The country or region. N
DataArea/Person/ContactInfo/Address/PostalCode string zipCode The zip code or postal code. N
DataArea/Person/ContactInfo/Address/AddressLine[1] string address1 The first line of the street address. N
DataArea/Person/ContactInfo/Address/AddressLine[2] string address2 The second line of the street address. N
DataArea/Person/ContactInfo/Address/AddressLine[3] string address3 The third line of the street address. N
DataArea/Person/ContactInfo/Address/UserData/UserDataField USERDATA - Used to pass additional parameters to the target command. N
DataArea/Person/ContactInfo/UserData/UserDataField USERDATA - Used to pass additional 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 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 will apply to all stores. N
DataArea/Person/UserData/UserDataField USERDATA - Used to pass additional parameters to the target command. N


Add or updating an address for a person:

Requests to add or update an address for a person will be mapped to com.ibm.commerce.usermanagement.commands.AddressAddCmd and com.ibm.commerce.usermanagement.commands.AddressUpdateCmd respectively. The requests 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 string action The action code. Valid values are... Add: to add an address for a person Change: to update an address for a person Y
DataArea/Sync/ActionCriteria/ActionExpression string commerceObject Action Expression. Must be specified...

  • Person/ContactList/ContactEntry

Y
DataArea/Person/PersonIdentifier/DistinguishedName string distinguishedName Distinguished name of the person, used along with the nickname to identify the person. Y
DataArea/Person/ContactList/ContactEntry/@contactNickName string nickName The nickname or identifier of the address being added. A person can have a collection of addresses, each with a nickname. The address that a user provides when registering is treated by the system as the person's own address and the system sets the nickname of that address to the person's logon ID. Y
DataArea/Person/ContactList/ContactEntry/ContactName/LastName string lastName Last name of the person. N
DataArea/Person/ContactList/ContactEntry/ContactName/PersonTitle string personTitle Title of the person, for example, Dr., Mr. or Ms. N
DataArea/Person/ContactList/ContactEntry/ContactName/FirstName string firstName First name of the person. N
DataArea/Person/ContactList/ContactEntry/ContactName/MiddleName string middleName Last name of the person. N
DataArea/Person/ContactList/ContactEntry/Telephone[1] string phone1 The person's primary phone number. N
DataArea/Person/ContactList/ContactEntry/Telephone[1]/@type string phone1Type The type of phone used for the person's primary phone number, for example TTY for hearing impaired, PCM for pulse-coded modulation, or CEL for mobile. This is a field of 3 characters. N
DataArea/Person/ContactList/ContactEntry/Telephone[1]/@publish string publishPhone1 Specifies whether the primary phone number is listed. N
DataArea/Person/ContactList/ContactEntry/Telephone[2] string phone2 The person's secondary phone number. N
DataArea/Person/ContactList/ContactEntry/Telephone[2]/@type string phone2Type The type of phone used for the person's secondary phone number, for example TTY for hearing impaired, PCM for pulse-coded modulation, or CEL for mobile. This is a field of 3 characters. N
DataArea/Person/ContactList/ContactEntry/Telephone[2]/@publish string publishPhone2 Specifies whether the primary phone number is listed. N
DataArea/Person/ContactList/ContactEntry/Email[1] string email1 The person's primary email address. N
DataArea/Person/ContactList/ContactEntry/Email[2] string email2 The person's secondary email address. N
DataArea/Person/ContactList/ContactEntry/Fax[1] string fax1 The person's primary fax number. N
DataArea/Person/ContactList/ContactEntry/Fax[2] string fax2 The person's secondary fax number. N
DataArea/Person/ContactList/ContactEntry/Address/@type string addressType 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 string city The city. N
DataArea/Person/ContactList/ContactEntry/Address/StateOrProvinceName string state The state or province. N
DataArea/Person/ContactList/ContactEntry/Address/Country string country The country or region. N
DataArea/Person/ContactList/ContactEntry/Address/PostalCode string zipCode The zip code or postal code. N
DataArea/Person/ContactList/ContactEntry/Address/AddressLine[1] string address1 The first line of the street address. N
DataArea/Person/ContactList/ContactEntry/Address/AddressLine[2] string address2 The second line of the street address. N
DataArea/Person/ContactList/ContactEntry/Address/AddressLine[3] string address3 The third line of the street address. N
DataArea/Person/ContactList/ContactEntry/Address/UserData/UserDataField USERDATA - Used to pass additional parameters to the target command. N
DataArea/Person/ContactList/ContactEntry/UserData/UserDataField USERDATA - Used to pass additional parameters to the target command. N

* Namespace prefixes 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 will contain the following information:

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

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

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

* Namespace prefixes ignored for simplicity.


Examples


Exceptions

All exceptions will be returned in the form of ConfirmBOD BODs with a ResponseCriteria element under the Confirm verb. They will contain the following information:

XPath* Type Description
DataArea/Confirm/ResponseCriteria/ChangeStatus/Code string The correlation identifier. Can be used to uniquely identified an exception in the server logs.
DataArea/Confirm/ResponseCriteria/ChangeStatus/ReasonCode string

The reason code, which is either a WebSphere Commerce system error code code if available, or the EC message key plus an optional secondary error code if the WebSphere Commerce system error code is unavailable (usually in the case of application exceptions).

DataArea/Confirm/ResponseCriteria/ChangeStatus/Reason string The exception message.

* Namespace prefixes ignored for simplicity.

Message mapping file used: SyncPersonBODMapping.xml


Examples

Related reference

Inbound Web services provided