Synchronize organization service

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

Typical use cases

  • Creating or updating an organization
  • Creating or updating an address for an organization

Endpoint URL and operation

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

Request

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

  1. Add or update an organization
  2. Add or update an address for an organization

Adding or updating an organization

Requests to add or update an organization are mapped to com.ibm.commerce.usermanagement.commands.OrgEntityAddCmd and com.ibm.commerce.usermanagement.commands.OrgEntityUpdateCmd. 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 stringactionThe action code. Valid values are as follows:
  • Add: to add an organization
  • Change: to update an existing organization
Y
DataArea/Sync/ActionCriteria/ActionExpression stringcommerceObject Action Expression. Must be specified as follows:
  • Organization
Y
DataArea/Organization/OrganizationIdentifier/DistinguishedName stringdistinguishedName Distinguished name of the organization.Y - when you update an organization

N - when you add an organization

DataArea/Organization/ParentIdentifier/DistinguishedName stringparentDNDistinguished name of the parent organization.Y - when you add an organization and OrganizationType equals 'OU'. When OrganizationType =O, this parameter is not mandatory; it defaults to Root Organization. This parameter applies only when you add an organization.
DataArea/Organization/OrganizationName stringorgEntityName Short name for organization (O) or organization unit (OU). Y - when you add an organization

N - when you update an organization

DataArea/Organization/OrganizationType stringorgEntityType Type of OrgEntity. Valid values are as follows: O: organization OU: organization unitY - when you add an organization. This parameter applies only when you add an organization.
DataArea/Organization/BusinessCategory stringbusinessCategory The business category, which describes the business that is performed by an OrgEntity.N
DataArea/Organization/Description stringdescription A description of the OrgEntity.N
DataArea/Organization/ContactInfo/Telephone[1] stringphone1The primary phone number of the organization.N
DataArea/Organization/ContactInfo/Telephone[1]/@type stringphone1Type The type of phone that is used for the primary phone number of the organization. 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/Organization/ContactInfo/Telephone[1]/@publish stringpublishPhone1 Specifies whether the primary phone number is listed. N
DataArea/Organization/ContactInfo/Telephone[2] stringphone2The secondary phone number of the organization.N
DataArea/Organization/ContactInfo/Telephone[2]/@type stringphone2Type The type of phone that is used for the secondary phone number of the organization. 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/Organization/ContactInfo/Telephone[2]/@publish stringpublishPhone2 Specifies whether the primary phone number is listed. N
DataArea/Organization/ContactInfo/Email[1] stringemail1The primary email address of the organization.N
DataArea/Organization/ContactInfo/Email[2] stringemail2The secondary email address of the organization.N
DataArea/Organization/ContactInfo/Fax[1] stringfax1The primary fax number of the organization.N
DataArea/Organization/ContactInfo/Fax[2] stringfax2The secondary fax number of the organization.N
DataArea/Organization/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/Organization/ContactInfo/Address/City stringcityThe city.N
DataArea/Organization/ContactInfo/Address/StateOrProvinceName stringstateThe state or province.N
DataArea/Organization/ContactInfo/Address/Country stringcountryThe country or region.N
DataArea/Organization/ContactInfo/Address/PostalCode stringzipCodeThe zip code or postal code.N
DataArea/Organization/ContactInfo/Address/AddressLine[1] stringaddress1The first line of the street address.N
DataArea/Organization/ContactInfo/Address/AddressLine[2] stringaddress2The second line of the street address.N
DataArea/Organization/ContactInfo/Address/AddressLine[3] stringaddress3The third line of the street address.N
DataArea/Organization/ContactInfo/Address/UserData/UserDataField USERDATA-Used to pass more parameters to the target command.N
DataArea/Organization/ContactInfo/UserData/UserDataField USERDATA-Used to pass more parameters to the target command.N
DataArea/Organization/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/Organization/ContextAttribute/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/Organization/ContextAttribute/AttributeValue[k]/StoreID string 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/Organization/UserData/UserDataField USERDATA-Used to pass more parameters to the target command.N

Adding or updating an address for an organization:

Requests to add or update an address for a person are 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:
  • storeId
  • langId
N
DataArea/Sync/ActionCriteria/ActionExpression/@actionCode stringactionThe action code. Valid values are as follows:
  • Add: to add an address for an organization
  • Change: to update an address for an organization
Y
DataArea/Sync/ActionCriteria/ActionExpression stringcommerceObject Action Expression. Must be specified as follows:
  • Organization/ContactList/ContactEntry
Y
DataArea/Organization/OrganizationIdentifier/DistinguishedName stringdistinguishedName Distinguished name of the organization.Y
DataArea/Organization/ContactList/ContactEntry/@contactNickName stringnickNameThe nickname or identifier of the address that is added or updated. An organization can have a collection of addresses, each with a nickname. The address that an organization provides during registration is treated by the system as the organization's own address. The system sets the nickname of that address to the organization's orgEntityName.Y
DataArea/Organization/ContactList/ContactEntry/ContactName/LastName stringlastNameSurname of the contact person.N
DataArea/Organization/ContactList/ContactEntry/ContactName/PersonTitle stringpersonTitle Title of the contact person, for example, Dr., Mr. or Ms. N
DataArea/Organization/ContactList/ContactEntry/ContactName/FirstName stringfirstName Given name of the contact person.N
DataArea/Organization/ContactList/ContactEntry/ContactName/MiddleName stringmiddleName Middle name of the contact person.N
DataArea/Organization/ContactList/ContactEntry/Telephone[1] stringphone1The primary phone number of the organization.N
DataArea/Organization/ContactList/ContactEntry/Telephone[1]/@type stringphone1Type The type of phone that is used for the primary phone number of the organization. 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/Organization/ContactList/ContactEntry/Telephone[1]/@publish stringpublishPhone1 Specifies whether the primary phone number is listed. N
DataArea/Organization/ContactList/ContactEntry/Telephone[2] stringphone2The secondary phone number of the organization.N
DataArea/Organization/ContactList/ContactEntry/Telephone[2]/@type stringphone2Type The type of phone that is used for the secondary phone number of the organization. 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/Organization/ContactList/ContactEntry/Telephone[2]/@publish stringpublishPhone2 Specifies whether the primary phone number is listed. N
DataArea/Organization/ContactList/ContactEntry/Email[1] stringemail1The primary email address of the organization.N
DataArea/Organization/ContactList/ContactEntry/Email[2] stringemail2The secondary email address of the organization.N
DataArea/Organization/ContactList/ContactEntry/Fax[1] stringfax1The primary fax number of the organization.N
DataArea/Organization/ContactList/ContactEntry/Fax[2] stringfax2The secondary fax number of the organization.N
DataArea/Organization/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/Organization/ContactList/ContactEntry/Address/City stringcityThe city.N
DataArea/Organization/ContactList/ContactEntry/Address/StateOrProvinceName stringstateThe state or province.N
DataArea/Organization/ContactList/ContactEntry/Address/Country stringcountryThe country or region.N
DataArea/Organization/ContactList/ContactEntry/Address/PostalCode stringzipCodeThe zip code or postal code.N
DataArea/Organization/ContactList/ContactEntry/Address/AddressLine[1] stringaddress1The first line of the street address.N
DataArea/Organization/ContactList/ContactEntry/Address/AddressLine[2] stringaddress2The second line of the street address.N
DataArea/Organization/ContactList/ContactEntry/Address/AddressLine[3] stringaddress3The third line of the street address.N
DataArea/Organization/ContactList/ContactEntry/Address/UserData/UserDataField USERDATA-Used to pass more parameters to the target command.N
DataArea/Organization/ContactList/ContactEntry/UserData/UserDataField USERDATA-Used to pass more parameters to the target command.N

* Namespace prefixes 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 an organization contains the following information:

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

A response to adding or updating an address for organization 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 in the form of ConfirmBOD BODs with a ResponseCriteria element under the Confirm verb. They 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 WebSphere Commerce system error code WebSphere Commerce system error codeif 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 stringThe exception message.

* Namespace prefixes are ignored for simplicity.

Message mapping file used: SyncOrganizationBODMapping.xml

Examples