Synchronize person service
The synchronize person service is an inbound web service responsible for adding or updating a person in WebSphere Commerce to synchronize WebSphere 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:
- Add or update a person
- 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:
| N |
| DataArea/Sync/ActionCriteria/ActionExpression/@actionCode | string | action | The
action code. Valid values are as follows: Add:
to add a person. Change: to update an existing person. | Y |
| DataArea/Sync/ActionCriteria/ActionExpression | string | commerceObject | Action Expression. Must be specified as follows:
| Y |
| DataArea/Person/ParentIdentifier/DistinguishedName | string | parentMember | Distinguished name of the parent organization. If unspecified, the default values are: o=default organization, o=root organization | N |
| DataArea/Person/Authentication/LogonID | string | logonId | Log on ID of the person. | Y |
| DataArea/Person/Authentication/Password | string | logonPassword | Password of the person. | Y - when you add a person N - when you update a person |
| DataArea/Person/Authentication/SecurityHint/Question | string | challengeQuestion | Challenge question to confirm the identity of a person. | 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 expired. Valid values are
as follows:
|
N |
| DataArea/Person/Authentication/@status | boolean | userStatus | Allows the person to have the logon ID disabled without removing
the person from the system.
| N |
| DataArea/Person/Authentication/UserData/UserDataField | USERDATA | - | Used to pass more 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 | Middle 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 that is used to display 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 as follows:
| 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 more 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 of this 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 more 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 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 | 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 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 | 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:
| 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 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* | Type | Maps to the following command parameter | Description | Required |
| ApplicationArea/BusinessContext/ContextData | USERDATA | - | Context Data. For example:
| N |
| DataArea/Sync/ActionCriteria/ActionExpression/@actionCode | string | action | The
action code. Valid values are as follows:
|
Y |
| DataArea/Sync/ActionCriteria/ActionExpression | string | commerceObject | Action Expression. Must be specified as follows:
| 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 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 | string | lastName | Surname 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 | Given name of the person. | N |
| DataArea/Person/ContactList/ContactEntry/ContactName/MiddleName | string | middleName | Middle 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 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 | 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 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 | 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:
| 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 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
- SyncPerson.xml - Adding a person
- SyncPersonAddress.xml - Adding an address for a person
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 | string | Member 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
- ConfirmBODPerson.xml - response of successfully adding or updating a person
- ConfirmBODPersonError.xml - response of successfully adding or updating an address
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 | string | The correlation identifier. Can be used to uniquely identify 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 are ignored for simplicity.
Message mapping file used: SyncPersonBODMapping.xml
Examples
- SyncPerson.xml
- SyncPersonAddress.xml
- ConfirmBODPersonError.xml- exception response when a required parameter is missing.