Introduction
The following article looks at the simplified web services available to Oracle Sales Cloud users for creating basic customer, contact, and other records. This is also documented in this MyOracleSupport whitepaper, however in this article you'll find our own examples and many usage tips.
If you search in Oracle Enterprise Repository for web services related to managing Sales Accounts (also known as Customers) then you'll find that several are returned.
- Sales Account Resource Service - related to the resources associate with the account.
- Sales Party - manage the party usage for a given party
Whilst these are available for use, exactly which to use for creating net-new customer records is not very clear. Angelo Santagata's blog has an example (from some time ago) however you'll notice it requires some familiarization with the underlying Trading Community Architecture (TCA) data model and the construction of a hierarchy of related components that make up the completed customer record (party, party-usage, location, address etc). In addition using the services above also involves obtaining and passing internal ID values (like PartyID) through the sequence of service calls. For many cases this is more work than is required.
Starting in Release 9 there was a set of web services which greatly simplifies the creation of Sales Accounts (Customers), Addresses, Contacts, Households, and the Relationships between them. These are listed in OER with titles beginning "Sales Cloud ..." as shown below.
![]()
In this article we will look at the Sales Cloud Account Service, however each service in this group have similar operations, interfaces, attributes, and characteristics. The service WSDL's for all of these can be found below, and they each include the following operations (just replace Account with the object name): createAccount, updateAccount, deleteAccount, mergeAccount (which combines update and insert), findAccount, and processAccount (used for bulkloading).
- https://[YourSalesCloudHost]/crmCommonSalesParties/AccountService?WSDL
- https://[YourSalesCloudHost]/crmCommonSalesParties/ContactService?WSDL
- https://[YourSalesCloudHost]/crmCommonSalesParties/AddressService?WSDL
- https://[YourSalesCloudHost]/crmCommonSalesParties/HouseholdService?WSDL
- https://[YourSalesCloudHost]/crmCommonSalesParties/RelationshipService?WSDL
Creating Sales Accounts / Customers
The key thing to note here is that most of the operations, including createAccount, accept similar values as the user interface, with no need for prerequisite calls to get internal ID's. As such the services will use the data provided to create new records such as address locations, and where additional context association is needed the user credentials associated with the web service request are used, such as for the Customer Account Owner value field (OwnerPartyId).
As you can see from the sample createAccount request below, the data input is simple.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soap:Body><ns1:createAccount
xmlns:ns1="http://xmlns.oracle.com/apps/crmCommon/salesParties/accountService/types/"><ns1:account
xmlns:ns2="http://xmlns.oracle.com/apps/crmCommon/salesParties/accountService/"><ns2:SourceSystem xsi:nil="true"/><ns2:SourceSystemReferenceValue xsi:nil="true"/><ns2:OrganizationName>Smith Power Supplies</ns2:OrganizationName><ns2:CEOName>John Smith</ns2:CEOName><ns2:Type>ZCA_CUSTOMER</ns2:Type><ns2:CreatedByModule>SALES</ns2:CreatedByModule><ns2:PhoneCountryCode>1</ns2:PhoneCountryCode><ns2:PhoneAreaCode>650</ns2:PhoneAreaCode><ns2:PhoneNumber>1234567</ns2:PhoneNumber><ns2:FaxCountryCode>1</ns2:FaxCountryCode><ns2:FaxAreaCode>650</ns2:FaxAreaCode><ns2:FaxNumber>7654321</ns2:FaxNumber><ns2:EmailAddress>newbusiness@jpowersuppinc.com</ns2:EmailAddress><ns2:URL>https://www.jpsuppwebsite.com</ns2:URL><ns2:PrimaryAddress
xmlns:ns3="http://xmlns.oracle.com/apps/crmCommon/salesParties/commonService/"><ns2:SourceSystem xsi:nil="true"/><ns2:SourceSystemReferenceValue xsi:nil="true"/><ns3:AddressLine1>1234 El Camino Real</ns3:AddressLine1><ns3:City>San Mateo</ns3:City><ns3:Country>US</ns3:Country><ns3:County>San Mateo</ns3:County><ns3:PostalCode>94401</ns3:PostalCode><ns3:State>CA</ns3:State></ns2:PrimaryAddress></ns1:account></ns1:createAccount></soap:Body></soap:Envelope>
In testing this we made a few observations compared to other payload samples available. Please review these if you encounter any problems:
- SourceSystem and SourceSystemReferenceValue attributes are not required to have any specific value.
- IndustryCodeType and the associated IndustryCode attributes are related to the CUSTOMER_CATEGORY system lookup, however when included can throw an exception unless matching data is configured (as it's a read-only attribute). It is not a required field and as such in this example it was removed.
- CreatedByModule was set to SALES so it is inline with records created by the UI.
- One the request is processed the Sales Account is available in the UI for use, as there is no additional approval or processing.
- The default type is ZCA_CUSTOMER for creating customers, however you can use ZCA_PROSPECT to create prospects also.
Finding The Account Records
All of these services support the standardized findCriteria used throughout Sales Cloud, and hence again requires no internal Id values. As used in the example below it is recommended to include some filtering or a fetchSize limit to avoid performance problems, and to use the findAttribute element in your request so to return only the attributes values you need, as by default the response payload contains dozens of attributes for each record.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:typ="http://xmlns.oracle.com/apps/crmCommon/salesParties/accountService/types/"
xmlns:typ1="http://xmlns.oracle.com/adf/svc/types/"><soapenv:Header/><soapenv:Body><typ:findAccount><typ:findCriteria> <typ1:fetchStart>0</typ1:fetchStart> <typ1:fetchSize>-1</typ1:fetchSize> <typ1:filter> <typ1:group> <typ1:conjunction>And</typ1:conjunction> <typ1:upperCaseCompare/> <typ1:item> <typ1:conjunction>And</typ1:conjunction> <typ1:upperCaseCompare>false</typ1:upperCaseCompare> <typ1:attribute>CreationDate</typ1:attribute> <typ1:operator>AFTER</typ1:operator> <typ1:value>2015-05-01</typ1:value> </typ1:item> </typ1:group> <typ1:nested/> </typ1:filter> <typ1:findAttribute>PartyUniqueName</typ1:findAttribute> </typ:findCriteria> <typ:findControl> <typ1:retrieveAllTranslations>false</typ1:retrieveAllTranslations> </typ:findControl></typ:findAccount></soapenv:Body></soapenv:Envelope>
If you are using Application Composer then you can use the SalesAccountVO to create/query these records or alternatively call the findAccount web service operation passing in the following equivalent map:
def findCriteria = [filter: [ group: [ [ item: [
[ attribute :'CreationDate', operator :'AFTER', value :[[item:'2015-05-01']] ],
] ] ] ], findAttribute:[[item:'PartyUniqueName']]]
def findControl = [ ]
def acts = adf.webServices.SimplifiedAccountService.findAccount(findCriteria, findControl)
def actlist = acts[0].Value
setAttribute('SelectedAccounts_c',actlist)
Of course you'd want to manipulate the returned Array before using the setAttribute, and recommended ways of doing this will be covered in a separate article related to handling web service responses in Groovy.
Updating Records
To use the updateAccount service operation you will need the PartyId value for your Sales Account.
This is available from either the createAccount or findAccount response payloads.
Using this you can use this operation to change any of the attributes available in the Sales Cloud Account SDO.
Customer Contacts and Relationships
The Sales Cloud Contacts service allows you to create contact records.
Contacts have an underlying type, specifying if they can be sold-to directly (type ZCA_CUSTOMER), for use as a prospect (type ZCA_PROSPECT), or are a standard Business Contact (type ZCA_CONTACT). When you create a contact records via the web service this defaults to the ZCA_CONTACT type which is recommended for basic use. In this case the type element is not included in the request payload (see the whitepaper for a sample).
Once records are created use the Sales Cloud Relationships Service createRelationship operation to associate your Contact with a particular Account/Customer. You do the association by supplying either the PartyID or the PartyNumber attributes for your Account and Contact records. Both are returned in the related create response payloads and again are also available in the findAccount / findContact operations.
In the following example the ObjectPartyId is the Account and the SubjectPartyId is the Contact. The relationship type and code ensure that this is shown on the UI under the list of contacts for this supplier, and you can specify start and end dates to setup accurate data for your users.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns1:createRelationship
xmlns:ns1="http://xmlns.oracle.com/apps/crmCommon/salesParties/relationshipService/types/"><ns1:relationship
xmlns:ns2="http://xmlns.oracle.com/apps/crmCommon/salesParties/relationshipService/"><ns2:ObjectPartyId>300000003709017</ns2:ObjectPartyId><ns2:SubjectPartyId>300000003647269</ns2:SubjectPartyId><ns2:RelationshipType>CONTACT</ns2:RelationshipType><ns2:RelationshipCode>CONTACT_OF</ns2:RelationshipCode><ns2:StartDate>2015-05-20</ns2:StartDate><ns2:EndDate>2025-12-31</ns2:EndDate><ns2:CreatedByModule>SALES</ns2:CreatedByModule><ns2:Comments>NEW CONTACT RELATIONSHIP</ns2:Comments></ns1:relationship></ns1:createRelationship></soap:Body></soap:Envelope>
Addresses and Households
These two additional services emulate the structure and functionality of the Account Service mentioned above, and for Households contacts can be associated through the relationship as also described.
New addresses are created as part of the top level object creation services, however if you wish to create more then this is possible using the Address Service.