5 SOAP APIs
The following SOAP APIs are available:
-
User Details: Users
-
Product Service: Product Records
-
Retrieve Product Specifications: Product Specifications
-
Project Activities: Project Activities
Figure 5-1 Overview of SOAP APIs
![This figure shows the SOAP APIs. This figure shows the SOAP APIs.](img/soap_apis.png)
Parameters and Filtering
Various parameters can be included in calls to the APIs, generally to define what data is to be returned, but can also control how records are returned. The following table lists some commonly used parameters.
Common Parameters
Parameter | Type | Description |
---|---|---|
offset |
int |
Used with pageSize to control the paging of a returned list of records. Specifies the starting point for the retrieval of records. If not specified, zero is assumed. For example, to retrieve 150 records:
|
batchSize |
int |
Used with offset to control the paging of a returned list of records. Specifies the number of entries in each page of returned list of records. If not specified, 30 is assumed. The maximum is 100. |
Note:
Date/Time parameters must be provided in the YYYY-MM-DD hh:mm:ss format.
When retrieving records, the returned XML only includes elements that actually contain data; empty elements are omitted.
The following example provides the first 50 Product Specifications that changed status to either Active or Off Range in May 2016. Searching with either fromDate or toDate specified without specStatus, will filter based on the last amended date of the Product Specification.
<soapenv:Envelope xmlns:soapenv="<<hostname>>/soap/envelope/"xmlns:v1="<<servicename>>/"> <soapenv:Header/> <soapenv:Body> <v1:getProductSpecification> <request> <batchsize>50</batchsize> <offset>0</offset> <specStatus>ACTIVE</specStatus> <specStatus>OFF_RANGE</specStatus> <fromDate>2016-05-01T00:00:00</fromDate> <toDate>2016-05-31T24:00:00</toDate> </request> </v1:getProductSpecification> </soapenv:Body>
User Details
This section describes the API for managing single sign-on between Brand Compliance and the JasperReports Server used by the Reports module. The following function is available:
-
userDetails: retrieves user information for the user currently logged into Brand Compliance
userDetails
Description
This API is used in the Reports Single Sign-On integration with the TIBCO JasperSoft JasperReports Server to allow the JasperReports Server to retrieve the user information for the user that is logged into Brand Compliance. A oneTimePad is given to the JasperReports Server for use in calling this API. For each oneTimePad, a single call is permitted. Attempting to use the same oneTimePad multiple times results in failures.
This API is used in the Reporting Single Sign-On integration. The oneTimePad is automatically generated when the user clicks the Reports link; it is not feasible to manually call this service.
The API can be tested by clicking the navigation link to the Reports module.
Note:
This service is superseded by the SSO Restful Service.
Endpoint address: /services/userDetails HTTP method: getUser
Request Details
The request contains a single value, oneTimePad, which is the identifier passed to the JasperReports Server when the Reports tab is opened.
Response Details
If the oneTimePad value matches a value stored in the application, the details of the currently logged in user are returned to the caller.
Error Messages
Element | Message | Meaning |
---|---|---|
oneTimePad |
Value not recognized: <###>. |
The oneTimePad value is not found or not specified |
oneTimePad |
userId cannot be null |
The user is not found |
Product Service
This section describes the API managing Product Records. The following functions are available:
-
createProduct: creates a new Product Record
-
updateProduct: update an existing Product Record
-
submitProduct: automatically detects whether a submitted Product Record is to be updated or created based on whether it already exists or not
Note:
The SOAP version of the Product Record API is only compatible with portals that are operating in single variant mode, where the Product Record represents just a single variant of the product.
createProduct
Description
Creates a new Product Record. Use this function to create new Product Records in Brand Compliance based on the data sourced from, the external system.
Dependencies: If linked to a supplier or site, the Supplier/Site must be present in the application and its record ID obtained. If assigning a Business Category, Product Technologist, or Other Contact the record must be present in the application and its record ID obtained. Product Technologist and Other Contacts may be omitted to default to TBC if the TBC user is present in the application. The status must be Active in order to be linked to a specification; for the status to be Active the Product Record must be linked to a supplier. For more information, see Dependencies.
Note:
The Use Alternative Code for Product SOAP API system parameter enables a facility for holding alternative supplier codes against Supplier records. This feature is of use in the external system that does not hold the Brand Compliance supplier codes.
If enabled, and the supplier code submitted by the API is not found in Brand Compliance, a secondary lookup will be performed to attempt to locate the Supplier using the alternative codes facility.
Endpoint address: /services/productService HTTP method: createProduct
Request Details
The body of the request contains a createProductRequest element to specify the details of the Product Record to create. Only the attributes that are to be populated on the created Product Record need to be included. As a minimum, this must include the fields shown in the following table.
Product Record Mandatory Fields
Field Name | Element Name |
---|---|
Product Title |
ProductName |
Status |
Status |
Variant Name |
ProductName |
Quantity |
Quantity |
Specification Type |
SpecificationType - see below |
Specification Type Format |
SpecificationTypeFormat - see below |
Technologist |
ProductTechnologist - see below |
Other Contacts |
OtherContacts - see below |
Supplier Details |
supplier |
Site Details |
site |
Example Request XML
This example shows the minimum requirement to be able to create a Product Record.
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ext="external.service.creations.micros.com" xmlns:sch="http://www.micros.com/schema"> <soapenv:Header/> <soapenv:Body> <ext:createProductRequest> <product> <sch:ProductNumber>ABC124</sch:ProductNumber> <sch:ProductName>AR Product</sch:ProductName> <sch:SupplierCode>A0001</sch:SupplierCode> <sch:Status>DRAFT</sch:Status> <sch:ProductTechnologist>TBC</sch:ProductTechnologist> <sch:OtherContacts> <sch:Contact> <sch:Name>TBC</sch:Name> <sch:Role>BUYER</sch:Role> </sch:Contact> <sch:Contact> <sch:Name>TBC</sch:Name> <sch:Role>PRODUCT DEVELOPMENT MANAGER</sch:Role> </sch:Contact> </sch:OtherContacts> <sch:Quantity>100g</sch:Quantity> </product> </ext:createProductRequest> </soapenv:Body> </soapenv:Envelope>
If a specification type has more than one format, such as a Food specification having separate formats for Food - UK and Food - US, the SpecificationTypeFormat element is used to specify the specification format and SpecificationType is used to identify the specification type, for example:
<sch:SpecificationType>FOOD</sch:SpecificationType> <sch:SpecificationTypeFormat>FOODUK</sch:SpecificationTypeFormat>
The code of the specification type/format must be used rather than the description.
ProductName populates the product name/title and the variant name.
ProductNumber populates the retailer's product code, such as SKU in the Product Coverage table.
Note:
The Allow Duplicate Product Codes for Product SOAP API system parameter controls whether the API permits the same product number to be used by different suppliers or not.
ProductBarcode and OuterBarcode populate the EAN Barcodes and Shipping Case Code barcodes on the Product Record, and are cascaded to the Product Specification when it is linked to the Product Record.
ProductTechnologist and OtherContacts populate the retailer contacts. If not specified, TBC will be defaulted (if the necessary User record has been configured).
Depending on the setup of Brand Compliance, there can be zero to many additional roles for which users must be nominated on a Product Record. For each Role of users, a Contact sub-element is added to OtherContacts which maps to the application's Product Record based on the Role element's value matching the Code of the user role in the application. The users are then loaded using the name supplied. For example, if the system has been set up to include the Buyer role in the Product Record's list of roles:
<sch:OtherContacts> <sch:Contact> <sch:Name>John Smith</sch:Name> <sch:Role>BUYER</sch:Role> </sch:Contact> </sch:OtherContacts>
See the associated WSDL for a full list of the attributes, and the Oracle Retail Brand Compliance Management Cloud Service Data Dictionary, Volume 3 - Product for details of their mapping to the fields within the Brand Compliance UI.
Response Details
If successful, an HTTP 200 response is sent with a body containing a createProductResponse root element, consisting of a Status element populated with SUCCEEDED.
If an error occurs, the createProductResponse root element contains the elements shown in the following table.
Returned Elements
Element | Type | Description |
---|---|---|
Status |
string |
Contains FAILED to indicate an error |
Message/Message/Severity |
string |
Contains ERROR to indicate an error |
Message/Message/Description |
string |
The error message, for example: Specification Type FOOD does not map to a single Specification Type Format in Brand Compliance, product not added |
Note:
Even if the request succeeds, additional warning messages may be included. Check the Status element for SUCCEEDED or FAILED to determine the success or failure of the call.
Errors are returned with a Severity element set to either ERROR (action failed) or WARNING (action completed with the invalid data omitted) and a Description element containing the error message.
Error Messages
Element | Message | Meaning |
---|---|---|
Error: Contact TBC not found in Brand Compliance Management Cloud Service, product not added. |
User TBC not found; required as the default for contacts if no valid user is specified |
|
SpecificationType |
Error: Specification Type <###> does not map to a single Specification Type Format in Brand Compliance Management Cloud Service, product not added. |
Specification type not found |
SpecificationTypeFormat |
Error: Specification Type Format <###> does not exist in Brand Compliance Management Cloud Service, product not added. |
Specification format not found |
ProductNumber |
Error: Product Number <###> already exists in Brand Compliance Management Cloud Service, product not added. |
Product Record already exists for the product number and supplier combination |
SupplierCode |
Error: Supplier <###> is not found in Brand Compliance Management Cloud Service, product with product number null not added. |
Supplier not found |
SiteCode |
Error: Site with code <###> not found in Brand Compliance Management Cloud Service, product not added. |
Site not found |
ProductBarcode |
Warning: EAN barcode <###> is invalid. |
Invalid barcode format - ignored |
OuterBarcode |
Warning: Shipping Case code <###> is invalid. |
Invalid barcode format - ignored |
ProductTechnologist |
Error: Contact <###> not found in Brand Compliance Management Cloud Service. |
Product Technologist not found |
ProductTechnologist |
Error: Contact <###> does not have PRODUCT TECHNOLOGIST role, product not added. |
User does not have the Product Technologist role |
OtherContacts |
Error: <###> role is not a valid product record contact role, product not added. |
Role not found |
OtherContacts |
Warning: Contact <###> not found in Brand Compliance Management Cloud Service. |
User not found - ignored |
LeadBusinessCategory BusinessCategories |
Warning: Business Category <###> not found in Brand Compliance Management Cloud Service. |
Business category not found - ignored |
CountryWhereSold |
Warning: Country Where Sold with code <###> not found in Brand Compliance Management Cloud Service. |
Business category not found - ignored |
updateProduct
Description
Updates an existing Product Record. Use this function to update a Product Record's details in Brand Compliance based on data sourced from the external system.
Endpoint address: /services/productService HTTP method: updateProduct
Request Details
The body of the request contains an updateProductRequest element to specify the updates to the Product Record. As a minimum, the values specified as mandatory for the createProduct function (see above) must be included.
The request content is similar to that for creating a Product Record. After the call, the Product Record is updated to match the request.
See the associated WSDL for a full list of the attributes, and the Oracle Retail Brand Compliance Management Cloud Service Data Dictionary, Volume 3 - Product for details of their mapping to the fields within the Brand Compliance UI.
Response Details
If successful, an HTTP 200 response is sent with a body containing an updateProductResponse root element, consisting of a Status element populated with SUCCEEDED.
If an error occurs, the updateProductResponse root element contains the elements shown in the following table.
Returned Elements
Element | Type | Description |
---|---|---|
Status |
string |
Contains FAILED to indicate an error |
Message/Message/Severity |
string |
Contains ERROR to indicate an error |
Message/Message/Description |
string |
The error message, for example: Specification Type FOOD does not map to a single Specification Type Format in Brand Compliance, product not added |
Note:
Even if the request succeeds, additional warning messages may be included. Check the Status element for SUCCEEDED or FAILED to determine the success or failure of the call.
Error messages are the same as createProduct, plus the messages shown in the following table.
Error Messages
Element | Message | Meaning |
---|---|---|
Error: API does not support multiple variants per Product Record. |
Updates may only be applied if the portal is operating in the mode where a separate Product Record is created for individual product variants (such as sizes) |
|
ProductNumber |
Error: Product Record not found in Brand Compliance Management Cloud Service (based on Product Number and Supplier Code). Product Record status must be Draft or Active. |
Product Record not found |
submitProduct
Description
Updates an existing Product Record or creates a new Product Record if it does not already exist. Use this function to pass data from the external system and have the API automatically determine whether a Product Record needs to be updated or created based on whether it already exists in Brand Compliance.
The Product Record to be updated is identified by matching Product Number, Product Name, and Supplier Code as a minimum.
Endpoint address: /services/productService HTTP method: submitProduct
Request Details
The body of the request contains a submitProduct element to specify the Product Record details. As a minimum, the values specified as mandatory for the createProduct function (see above) must be included.
This service determines if the specified product already exists and if so, updates it (per updateProduct above). Otherwise, it creates the product (per createProduct above).
See the associated WSDL for a full list of the attributes, and the Oracle Retail Brand Compliance Management Cloud Service Data Dictionary, Volume 3 - Product for details of their mapping to the fields within the Brand Compliance UI.
Response Details
If successful, an HTTP 200 response is sent with a body containing a submitProductResponse root element, consisting of a Status element populated with SUCCEEDED.
Error Messages
If an error occurs, the submitProductResponse root element contains the elements shown in the following table.
Returned Elements
Element | Type | Description |
---|---|---|
Status |
string |
Contains FAILED to indicate an error |
Message/Message/Severity |
string |
Contains ERROR to indicate an error |
Message/Message/Description |
string |
The error message, for example: Specification Type FOOD does not map to a single Specification Type Format in Brand Compliance, product not added |
Note:
Even if the request succeeds, additional warning messages may be included. Check the Status element for SUCCEEDED or FAILED to determine the success or failure of the call.
Retrieve Product Specifications
This section describes the API for Product Specifications. The following function is available:
-
getProductSpecificationV1: retrieves a list of Product Specifications in a page list
getProductSpecificationV1
Description
Retrieves a list of Product Specification in a paged list. Use this to extract specifications from Brand Compliance for use in the external system, using parameters to filter the returned specifications to meet the desired selection criteria.
Endpoint address: /services/getProductSpecificationV1 HTTP method: getProductSpecification
Request Details
Parameters are passed as URI parameters
URI Parameters
Parameter | Mandatory/Optional | Type | Multiple Value Separator (~) Supported? | Example | Validation |
---|---|---|---|---|---|
offset |
Mandatory |
int |
No |
60 |
>=0 |
batchSize |
Mandatory |
int |
No |
30 |
>0 and <=100 |
specType |
Optional |
string |
Yes |
FOOD |
FOOD FNF CNF PRODUCE BWS |
language |
Optional |
string |
Yes |
en_GB |
The Code for the required Language, such as en_GB. Specifying a preferred language will return only values in that language. If not specified, the base language is assumed |
specStatus |
Optional |
string |
Yes |
RETAILER_DRAFT |
SUPPLIER_DRAFT RETAILER_DRAFT COLLABORATIVE_DRAFT GATE_STEP PART_PACK_COPY_SENT PACK_COPY_SENT PACK_COPY_READY READY_FOR_AUTHORISATION SUPPLIER_AUTHORISED ACTIVE OFF_RANGE DE_LISTED SUPERSEDED NOT_PROGRESSED APPROVE_FOR_LABELLING PRODUCE_DRAFT PRODUCE_PACK_COPY PRODUCE_APPROVED PRODUCE_ARCHIVED |
countryWhereSold |
Optional |
string |
Yes |
FOOD_COUNTRY_WHERE_SOLD |
The Code for the required Country Where Sold. |
productNumber |
Optional |
string |
Yes |
12345 |
Filters on the Product Number column of the Product Coverage table. |
sectionType |
Optional |
string |
Yes |
RECIPE AND RAW MATERIALS |
MAIN DETAILS RECIPE AND RAW MATERIALS NUTRITION ALLERGY AND DIETARY ADVICE PACKAGING ADVANCED PACKAGING STORAGE OTHER LABELLING COPY CLAIMS SUBSTANTIATION PROCESS CONTROLS BATCH CODING PRODUCT APPROVAL REQUIREMENTS POST LAUNCH INFORMATION COMPONENTS FNF STORAGE PRODUCT REQUIREMENTS COUNTER TICKET PRODUCT CHARACTER COMP |
productCoverage |
Optional |
string |
Yes |
Chicken (500g) |
Filters on the Product Name column of the Product Coverage table. |
supplier |
Optional |
string |
Yes |
A0001 |
Filters on the Primary Sites supplier code for Produce Specifications or the Supplier code for all other types of Specification. |
site |
Optional |
string |
Yes |
A0001-001 |
Filters on the code of the Sites in the Primary Sites table of the Product Specification. Use the full site code incorporating the Supplier Code, such as A0001-001. |
fromDate |
Optional |
string |
No |
2013-06-10T09:00:00 |
Can be used in conjunction with toDate to form a date range or can be specified individually. |
toDate |
Optional |
string |
No |
2013-06-10T09:00:00 |
Can be used in conjunction with fromDate to form a date range or can be specified individually. |
For example, to retrieve the Main Details and Nutrition sections for active Food specifications where the product number is ABC001 from a specific supplier/site, the request would be:
<request> <batchsize>100</batchsize> <offset>0</offset> <specStatus>ACTIVE</specStatus> <specType>FOOD</specType> <countryWhereSold>UK</countryWhereSold> <productNumber>ABC001</productNumber> <language>en_GB</language> <sectionType>MAIN DETAILS</sectionType> <sectionType>NUTRITION</sectionType> <supplier>A0001</supplier> <site>A0001-0001</site> <fromDate>2016-01-01T01:00:00</fromDate> <toDate>2016-10-01T01:00:00</toDate> </request>
If no filtering is required, omit the parameter from the call. For example, if all specification types are to be included, omit the specType element (rather than including it with no value specified).
If multiple values for a parameter are to be included, repeat the parameter in the call. For example if Main Details and Nutrition section types are to be returned, include two sectionType elements in the call, one for MAIN DETAILS and one for NUTRITION.
Searching with either fromDate or toDate specified, as well as one or more specStatus, filters the specifications on the Status Change History. Use this to retrieve specifications that changed to a specific status during a date range.
Searching with either fromDate or toDate specified without specStatus filters on the specification's last amended date.
Response Details
If successful, an HTTP 200 response is sent with a body containing details of the specifications that match the selection criteria.
See the associated WSDL for a full list of the attributes, and the Oracle Retail Brand Compliance Management Cloud Service Data Dictionary, Volume 4 - Product (Food Specification), Oracle Retail Brand Compliance Management Cloud Service Data Dictionary, Volume 5 - Product (CNF Specification), Oracle Retail Brand Compliance Management Cloud Service Data Dictionary, Volume 6 - Product (FNF Specification), Oracle Retail Brand Compliance Management Cloud Service Data Dictionary, Volume 7 - Product (BWS Specification), and Oracle Retail Brand Compliance Management Cloud Service Data Dictionary, Volume 8 - Product (Produce Specification) for details of their mapping to the fields within the Brand Compliance UI.
Error Messages
Element | Message | Meaning |
---|---|---|
offset |
Unmarshalling Error: Exception Description: An error occurred unmarshalling the document Internal Exception: org.xml.sax.SAXParseException; cvc-maxInclusive-valid: Value '9999999999999999' is not facet-valid with respect to maxInclusive '2147483647' for type 'int'. |
Invalid offset value |
offset batchSize |
Unmarshalling Error: Exception Description: An error occurred unmarshalling the document Internal Exception: org.xml.sax.SAXParseException; cvc-datatype-valid.1.2.1: '?' is not a valid value for 'integer'. |
Non-numeric offset value Non-numeric batch size value |
batchSize |
<errorCode>INVALIDBATCHSIZE <errorMessage>The Batch Size must be between 1 and 100 |
Invalid batch size No batch size provided No batch size tag |
specType |
<errorCode>INVALIDSPECTYPE <errorMessage>The Spec Type <###> does not exist |
Specification type not found |
specStatus |
<errorCode>INVALIDSPECSTATUS <errorMessage>The Status <###> does not exist |
Spec Status not found |
countryWhereSold |
<errorCode>INVALIDCOUNTRYWHERESOLD <errorMessage>The Country Where Sold <###> does not exist |
Country not found |
language |
<errorCode>INVALIDLANGUAGE <errorMessage>The Language <###> does not exist |
Language not found |
sectionType |
<errorCode>INVALIDSECTIONTYPE<errorMessage>The Section Type does not exist |
Section type not found |
fromDate toDate |
Unmarshalling Error: Exception Description: An error occurred unmarshalling the document Internal Exception: org.xml.sax.SAXParseException; cvc-datatype-valid.1.2.1: '?' is not a valid value for 'dateTime'. |
Invalid date format |
Project Activities
This section describes the API for Artwork integration. The following function is available:
-
Activity Management: updates existing Artwork activities
Activity Management
Description
Updates the sub status of existing Artwork Project Activities. This function is used for the integration of Brand Compliance with an external Artwork Management system, to update the status of an artwork activity from the external system.
Note:
This service has been superseded by the Artwork Restful Service.
Endpoint address: /services/activityManagement HTTP method: updateActivityStatus
Request Details
The body of the request contains an updateActivityStatus/activityUpdateRequest element consisting of the elements shown in the following table.
Request Elements
Element | Type | Description |
---|---|---|
activityName |
string |
Project activity's name |
activityRecordId |
string |
Project activity record's internal ID |
projectId |
string |
ID business key to the Project record |
projectRecordId |
string |
Project record's internal ID |
subStatusCode |
string |
Code business key to the activity's sub status |
After the call, the Project Activity record's sub status is updated to match the request.
See the associated WSDL for a full list of the attributes, and the Oracle Retail Brand Compliance Management Cloud Service Data Dictionary, Volume 9 - Project for details of their mapping to the fields within the Brand Compliance UI.
Response Details
If successful, an HTTP 200 response is sent with a body containing an updateActivityStatusResponse root element, consisting of a return element populated with SUCCESS.
Error Messages
If an error occurs, the updateActivityStatusResponse root element's return element will contain FAILURE.