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

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: A call with offset = 0 and pageSize = 50 returns the first 50 records. Then, a call with offset = 50 and pageSize = 50 returns the next 50. Then, a call with offset = 100 and pageSize = 50 returns the final 50.
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.

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:

A call with offset = 0 and pageSize = 50 returns the first 50 records.
Then, a call with offset = 50 and pageSize = 50 returns the next 50.
Then, a call with offset = 100 and pageSize = 50 returns the final 50.

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.

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).

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 FINISHED PRODUCT STANDARDS 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.