| Oracle® Retail Brand Compliance Management Cloud Service Implementation Guide Release 18.1 F18526-07 |
|
 Previous |
 Next |
| Oracle® Retail Brand Compliance Management Cloud Service Implementation Guide Release 18.1 F18526-07 |
|
Previous |
Next |
The APIs exposed by Brand Compliance are implemented in one of two formats, SOAP web services or RESTful web services. In both cases, requests and responses are normally in an XML format.
The APIs are already built and available for clients to build services for their external applications to utilize. The external system makes a call to Brand Compliance using HTTPS. If the external system is validated (that is, it is enabled in the Admin area of Brand Compliance and the login user ID and password match), the call is accepted.
Calls will typically allow for the retrieval, creation, update, and in some cases deletion, of data through the API. Each call is logged in the Web Service Log in Brand Compliance, with the request and response messages being recorded as appropriate.
A call may contain a number of parameters or filters to determine the records to be returned or updated, or to identify where to create a new record, such as to filter Product Specification of a certain type, status and so on.
In general, APIs exposed by Brand Compliance as web services use XML messages for both requests and responses. Exceptions to this are RESTful services where the use of an XML request is replaced by the use of URI parameters in a GET call. The APIs do not support other message formats, such as JSON.
The XML data schemas are written to allow for both forwards and backwards compatibility. All elements within the XML schemas are marked as optional. The element names are ordered so that new fields are added after existing elements and, within each sequence of elements, the last element is always an any element so that fields added in future versions are ignored by clients that are using an old version of the schema. For example:
<xs:complexType name="fpsMicroTestLocaleDataFullDTO">
<xs:sequence>
<xs:element form="qualified" minOccurs="0" name="description" type="xs:string"/>
<xs:element form="qualified" minOccurs="0" name="locale" type="xs:string"/>
<xs:element form="qualified" minOccurs="0" name="id" type="xs:long"/>
<xs:element form="qualified" minOccurs="0" name="createdOn" type="xs:string"/>
<xs:element form="qualified" minOccurs="0" name="updatedOn" type="xs:string"/>
<xs:any maxOccurs="unbounded" minOccurs="0" namespace="##other" processContents="lax"/>
</xs:sequence>
</xs:complexType>
The element names in the XML Schemas are defined by the core system and do not change in specific implementations. If an implementation has additional fields that have been added to the system (the implementation is non-core), those fields may be exposed after the core fields (before the xs:any element) and will incur a maintenance overhead in later versions to cope with any additional core fields added after the custom fields.
Data types in the XML Schemas are the standard datatypes for XSDs, WSDLs, and WADLs. Values should be entered as described on the following web site:
http://www.w3.org/TR/xmlschema-2/
The following table lists the common data types used in the Brand Compliance schemas:
Data Types
| Type | Example |
|---|---|
| xs:string | A normal string |
| xs:string | <![CDATA[A String with <br/> html data]]> |
| xs:long | 9223372036854775807 |
| xs:int | 2147483647 |
| xs:short | -32768 |
| xs:boolean | true or false |
| xs:boolean | 1 or 0 |
| xs:date | 2015-01-30 |
| xs:dateTime | 2015-01-30T23:59:59 |
The Brand Compliance APIs are web services in both SOAP and RESTful architectural styles. In general, the SOAP services are developed for specific requirements or are historical services. Unless there is a definite requirement for a SOAP implementation of a service, any new services or new versions of services are implemented using the RESTful architectural style.
Due to the format of the XML schemas as described above, most revisions of the web services should be forwards and backwards compatible to allow clients of those web services to be upgraded and developed without binding the lifecycle of the client services to the upgrade cycle of Brand Compliance.
Where the necessary changes to a service cannot be made compatible with previous versions, a new endpoint will be created to expose the changed service. If possible, the previous version of the service will remain available at the original endpoint to enable existing and legacy clients to continue to work, but will be noted as deprecated in documentation to encourage developers of clients to the services to avoid using it.
All calls to APIs exposed as web services are logged within the application and can be viewed by logging into Brand Compliance as a Power User, navigating to Company > Admin> Notifications, and choosing the Web Service Log option. For each call, the name of the web service, date and time of the call, status (in progress/completed/failed), duration of the call (not available for In Progress calls), and a list of error messages if the call failed are shown.
The request and response XMLs are attached to each web service log entry. If a request does not contain XML, no attachment is created.
This section describes how to access the APIs.
If enabled within the portal, an API is accessible while the portal is online. The support for a portal's availability is subject to the client's service level agreement.
Updates to the APIs are applied as per changes and fixes to the application. Each release involves a scheduled period of downtime. Details of the change and impact are covered in the supporting Release Notes.
|
Note: After a Brand Compliance upgrade release, it may be necessary to change the URLs that the external system uses to call the APIs. |
The APIs, made available by Brand Compliance, are all web services implemented using either a SOAP or RESTful architecture.
The web services are exposed over HTTPS and require HTTP Basic authentication in order to access the service requested.
In order to authenticate with Brand Compliance when accessing an API deployed as a web service, a user name and password must be supplied for HTTP basic authentication. Within Brand Compliance, the External System record defines the user names and passwords that have access to the web services.
To see the list of existing External System records, log in to Brand Compliance as a Power User, navigate to Company > Admin > Roles and Permissions, and select the External Systems option.
To create a new External System:
Select the Actions > New action to open up a tab for creating an External System.
Enter a Login ID (User Name) and select the Actions > Save option.
To set the password to be used by the External System, select the Actions > Change Password option.
Select the Actions > Save action. The new user name and password are active and available for use.
The passwords used for External Systems are validated against the same criteria as the passwords for interactive users of Brand Compliance. It is likely that a minimum length, mixed case, and digits will be required for the password, depending on the setup of the system.
In all installations of Brand Compliance, a full list of the deployed web services can be found at /services.
For example, for a system where the application is deployed to URL https://www.example.com/brandCompliance, you can retrieve a list of all services from https://www.example.com/brandCompliance/services.
|
Note: In order to access the /services page, the user must first be logged in/authenticated with the Brand Compliance portal.When downloading the WSDL or WADL files, if prompted for further credentials, enter the Login ID and Password of the External System account. |
Change History Log
Updates made to Brand Compliance records through the APIs are shown in the record's Change History log with user shown as System. The Change History log data is not included in the XML payload.
Status Change History Log
For records that are subject to workflow, their Status Change History data is included in the XML payload, as follows:
Each row in the record's Status Change History table is represented by a statusHistory element. It is populated accordingly when data is retrieved.
When a new record is created, a row can be added to the Status Change History table by populating the contents of the statusHistory element.
When updating a record, the only column of the Status Change History table that may be changed by populating the statusHistory element is the Comments column.
It is not possible to remove rows from the Change History table.
Status Changed By can be omitted if required, in which case within the application, the Status Change History table will display the system text value System in place of a user name. Or, Status Changed By can be populated with a valid user (standard validation applies).
The contents of the statusHistory element are as follows:
<statusHistory>
<comments>
<localeData>
<locale>
<statusFrom>
<statusTo>
<id>
<id>
<createdOn>
<updatedOn>
<statusChangedBy>
<code>
<disabled>
<externalAuthenticationUser>
<timeZone>
<userType>
<id>
createdOn and updatedOn are set by the application when the record is created or modified.
statusChangedBy can only be set when the record is created, and can either be:
omitted, to denote the System was responsible, or,
a simpleUserDTO structure, whereby the child tag of <id> or <code> is used to specify the relevant user.
comments can optionally be specified during creation or update. If not specified, the application will show a dash.
localeData can be specified during creation only.
Where values are submitted but not permitted to update the status change history, they will be ignored.
For details of the contents of the Change History tables, see the Product Record page in the Oracle Retail Brand Compliance Management Cloud Service Data Dictionary, Volume 3 - Product data dictionary.
|
Note: The above rules for making updates to the status change history currently apply to the Product Records REST API only. In time, it will also apply to other records that have workflow, such as Projects and their Activities, Audits and their Issues, Suppliers and their Sites, Scorecards, and Product Specifications.However, the defaulting of System in place of a user name within the application does apply to all records with a Status Change History table. |
This section provides information on aspects of security you need to consider.
Unlike interactive logins for users, the use of web services does not permit warnings to be included in the returned messages. Also, there is no guarantee that there is someone handling the call in order to interpret any warnings about password expiry. Therefore, Brand Compliance does not currently apply the password lifetime rules to External Systems.
|
Note: It is recommended that the passwords used for accessing APIs deployed as web services are changed regularly and that passwords are not reused or changed in such a way that the next value is predictable, such as, do not change from Password11 to Password12. |
The passwords used to access the Brand Compliance APIs should be stored securely to prevent potential attackers from being able to masquerade as an authorized system.
In Brand Compliance, certain fields allow the display of HTML-formatted data. Such data is cleansed before display in Brand Compliance to ensure that any attempts at Cross-Site Scripting (XSS) attacks are mitigated, but this cleansing is not applied within the APIs. Therefore, it is advisable to cleanse any HTML-formatted data before it is displayed to users.
Many of the APIs published by Brand Compliance provide access to manage all of the records of a given type. With certain records, the fields accessible through the API are a subset of the fields within Brand Compliance. Any updates leave those fields unchanged. An example of this is the password-related fields on the User record, none of which are exposed in the APIs.
As all of the APIs are exposed as web services over HTTPS, it is necessary for callers to communicate over SSL/TLS using the ciphers that the Brand Compliance servers accept. To ensure optimal security, it is advised that standard certificate checks are in place and not disabled. In the case of Apache CXF, the Client TLS Parameter disableCNCheck should be left as false.
Updates made to Brand Compliance records through the APIs are shown in the record's Change History log with user shown as System.
Certain characters within URLs are reserved for a special meaning. In order to avoid calls that contain these characters being blocked by the API's security, the characters must be encoded and passed as plain text.
The reserved characters include ";", "/", "?", ":", "@", and "=", all of which could be present in the parameters passed to Brand Compliance APIs - such as within email addresses or within the names of users, products, or suppliers.
UTF-8 URL encoding should therefore be applied to all calls to the Brand Compliance APIs. The APIs will automatically decode the values on receipt.
For example, an un-encoded call of: …/services/rest/user/byKey/john.smith@example.com
should be encoded as:
…/services/rest/user/byKey/john.smith%40example.com
If a call comprises multiple values, each must be encoded individually.
This section describes how data is returned for fields that have their values derived by referencing a glossary or system text, such as the selections made from a configurable list of values.
Fields that have their values selected from a glossary of configurable options generally have the code, description, and language translations of the selected value returned, along with the id reference to the glossary record.
The language translations are contained within a localeData element. Prior to release 18.0, a separate localeData element was returned for each language the portal had configured, now just the languages that the portal actually has active are returned. If a translation is not present for a language, the element is omitted, so if the portal has no alternative languages active, just a localeData element for the base language is returned.
|
Note: Some APIs allow a locale parameter to be passed to optionally return a specific language, or languages. However, use of the parameter can have an impact on the call's response time, due to the additional selection processing. |
Certain reference fields have their options defined as system text rather than a configurable glossary. Referred to as enumerations, these are used where the selections are generally static, such as Yes/No options. Prior to release 18.0, just the code of an enumeration was returned, now the description of enumeration value is also returned as a description element.
Certain reference fields allow for a statement to be selected from a glossary and inline values entered after selection. Referred to as editable text selectors, these are used to build statements with variable content, but using a consistent format; for example, to describe cooking instructions in a common way without having to have an entry in the glossary for every permutation of time and temperature. Prior to release 18.0, just the separate statement and value elements were returned, now a packCopyText element containing the formed statement is also returned.
This section summarizes the key aspects of the API process:
The external system makes a call to Brand Compliance using HTTPS. The external system must be registered in Brand Compliance, and the user ID and password must match.
Calls to RESTful services use the GET, POST, PUT, and DELETE methods to retrieve, create, update, and delete records respectively. Calls to SOAP services use a predefined set of methods to perform the operations.
Each call is logged in the Web Service Log in Brand Compliance. The request and response XML messages are attached to the logs.
A predefined set of parameters is available to apply filters to the call, to retrieve a specific record or set of records.
Data is returned as XML, as defined by the associated WADL or WSDL schema. Only elements that contain data are returned; empty elements are omitted.
For RESTful APIs, an initial GET call to the service returns the unique internal key ID of the returned records in either the recordId or the id element. The record ID is then used in a subsequent call using a URI to retrieve the record's full XML data set, or to perform an update operation.
Update functions require the full set of fields and their values to be passed, as the full contents of the record are replaced. If all fields are not present in the external system, the update process would need to first retrieve the current contents of the record from Brand Compliance before applying the changes to that data set, and submitting the full data set as the update.
There could be several initiators for the data exchange, including the following:
Human initiation, where an individual makes the request, such as by clicking a button to run the request.
End user action, where the completion of an activity in the external system triggers the exchange.
Scheduled request (or polling), where the external system sends or checks for data on a regular basis. For example, it may be looking for newly created Product Records or Specifications with a change in status.
For security purposes, the APIs rely on the external system polling, retrieving or submitting calls to the APIs. Brand Compliance does not push data externally.
The nature of the APIs may require multiple requests to be made, for example:
Request a list of Product Records with their IDs.
Request the timestamp reference for each Product Record.
Identify any Product Records changed or created within a given time scale.
Request the full details for that Product Record.
These types of requests can be automated. The external system is altered to enable the operations to take place in sequence according to a pre-defined algorithm.
Certain modifications can also be made to the external system to enable the storage of data returned from Brand Compliance. For example, if the external system requests a record to be created in Brand Compliance, a confirmation response is sent, containing the record ID. This ID may then be stored in the external system for future reference.
