1. Implementation Guide
  2. RESTful APIs

4 RESTful APIs

The following RESTful APIs are available:

Figure 4-1 Overview of RESTful APIs

This figure shows an overview of the RESTful APIs.

Note:

Only minimal business logic and validation is applied by the Supplier Evaluation REST APIs.

When creating or updating records, all values must be included. If a value or element is omitted from the XML, the field contents will be cleared when updating the record.

Generally, only the validation necessary to ensure the system's referential integrity is applied when updating records through the APIs. It is therefore possible to set the contents of some fields with values that are rejected when the user manually edits or validates the record through the UI. In some cases, it may be necessary to regress these records back to a prior status in order to edit and correct values that have been set incorrectly through the UI.

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:

  1. A call with offset = 0 and pageSize = 50 returns the first 50 records.

  2. Then, a call with offset = 50 and pageSize = 50 returns the next 50.

  3. Then, a call with offset = 100 and pageSize = 50 returns the final 50.

pageSize

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.

isActive

Boolean

Used to only return records that are flagged as being active (TRUE).

modifiedSince

string

Used to locate records that have been created or updated since a specific date/time.

modifiedUntil

string

Used to locate records that have been updated or created until a specific date/time.

When a list of records is returned, it may include a previousPage and nextPage element. These elements provide URI links to the previous or next pages of records respectively. A totalRecords element is included that shows the total number of records available for retrieval.

For example, using the List of Values function to retrieve a list of User records, where there are 150 records to be retrieved, with the pageSize parameter set to 50 returns the first 50 records within entity elements, along with a nextPage element containing a URI link to the next 50 records which can be used to retrieve the next 50 records. When the second page of 50 records are returned, the XML includes a nextPage URI link to the final 50 records, along with a previousPage URI link to the first 50. The following graphic illustrates this example.

Figure 4-2 Example of Retrieving a List of Users

This figure shows an example of retrieving a list of users.

The totalRecords element shows the total number of retrievable records. The previousPage and nextPage elements are only present if there are previous and/or next pages to be retrieved.

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 details of the returned records are contained in an entities element, and repeated in an entryArray element. The entryArray element is a representation from the Java objects and can be ignored.

Where a date/time is passed in as a parameter to an endpoint, such as fromDate and toDate, validation checks for a valid date/time. If not valid, an HTTP 417 is returned, along with an XML error message detailing the exact issue with the date/time.

Error Messages

The Supplier Evaluation APIs use standard web services messaging protocols to notify the success or failure of a call to the service. Where an API handles a specific error condition, details of the returned message can be found in the following sections. The following table lists various generic error messages that may be returned by calls to any of the APIs.

Generic Error Messages

Element Message Meaning

userId

HTTP Status 401 - Bad credentials

User ID or password is invalid

Password

HTTP Status 401 - Bad credentials

User ID or password is invalid

Disabled

HTTP Status 401 - User is disabled

External System account is not enabled in Supplier Evaluation

offset

HTTP 417 IllegalStateException: Offset must be a positive integer

Invalid offset value - must be between zero and 2,147,483,647

offset

HTTP 404 Not Found

Not numeric or an integer

pageSize

HTTP 417 IllegalStateException: The Page Size must be between 1 and 100

Invalid page size value

HTTP 404 Not Found

Record cannot be located due to an invalid key or ID

HTTP 417 Expectation Failed

Record cannot be located due to an invalid ID

HTTP Status 500 - Internal Server Error

Unspecified internal error occurred

HTTP Status 500 - Internal Server Error

Non-numeric value in numeric parameters

modifiedSince

HTTP 417 <errorMessage>

Not a valid date, whereby <errorMessage> will identify the issue

For example: IllegalInstantException: Cannot parse "2018-03-25 01:00:00": Illegal instant due to time zone offset transition (Europe/London)

In this example, due to the clocks moving forward (in the server's time-zone), the passed in date is invalid

modifiedUntil

HTTP 417 <errorMessage>

Not a valid date, whereby <errorMessage> will identify the issue (see example above)

HTTP 400 Bad Request

Malformed XML, or general error in content of the XML

Wildcard Searches

The % character can be used as a wildcard filter when locating the records.

Using the % at the start of the string will search for matches where the given string ends with the text being searched for, for example, %smith could be used to search for all users with a surname of smith.

Using the % at the end of the string will look for matches where the given string begins with the text being searched for, for example, mark% could be used to search for all users with the name mark.

The following table shows which APIs and functions support the use of wildcards.

Wildcard Searches

API Function

User

List of Values

Supplier

List of Values

Site

List of Values

Contact

List of Values

Retrieve Supplier Contact Record by Business Key

Retrieve Site Contact Record by Business Key

Business Category

List of Values

Task

List of Values

Urgent Items

Number of Urgent Items

Notes:

  • Wildcard searches are not case sensitive so, for example, searching a name field for John Smith or john smith will return the same matches.

  • When searching glossary parameters, be aware that they relate to the code (not the description) of the glossary entry.

  • Wildcard searches can typically be applied to parameters that are string type. See the Wildcard Search Supported column in the APIs’ List of Values functions for which URL parameters support it.

Deleted Records

By default, soft deleted records are returned by the APIs (the XML contains a deleted element, which is set to true). To exclude soft deleted records, it is necessary to use a softDelete=false parameter when calling the API. For example:

/creations-core/services/rest/site?softDelete=false

UserRestService

This section describes the API for managing retailer and supplier users. The following functions are available:

List of Values

Description

Retrieves a list of users in a paged list. Use this function to retrieve a simple list of user names and IDs, or to locate User record IDs prior to a retrieve or update operation. Parameters are available to apply specific selection criteria for filtering the returned records.

Endpoint address: /services/rest/user HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/ Optional Value Type Multiple Value Separator (~) Supported? Wildcard Search Supported? Example
offset Optional int No No 60
pageSize Optional int No No 30
name Optional string No Yes John Smith
jobTitle Optional string No Yes Process Manager
language Optional string No Yes en_GB
country Optional string No Yes UK
userRoles Optional string No Yes PROCESS ADMINISTRATOR
userType Optional string Yes No RETAILER
authorityProfiles Optional string No Yes PROCESS MANAGER
siteStatus Optional string Yes No ACTIVE~INACTIVE
supplierActive Optional string No No

true returns active users

no value returns both active and inactive users
modifiedSince Optional string No No 2015-05-19 13:30:39
modifiedUntil Optional string No No 2015-05-19 13:30:39

Example URLs

…/services/rest/user/?offset=2&pageSize=20 …/services/rest/user/?siteStatus=Active …/services/rest/user/?name=Frank%

Response Details

For a successful response, XML is returned with a UserLinkList root element containing an entries element for each matched user. The entries element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

User record's internal ID

recordLink

string

URI to the UserRestService Retrieve record service for this user

loginId

string

Login ID / business key to the User record

name

string

User's name

The returned XML also contains a totalRecords element, which states the total number of retrievable records that match the filter parameters.

Error Messages

In the event that an error occurs, an HTTP 500 response is sent.

Retrieve Record by ID

Description

Retrieves a single User record's details using the record's internal unique ID (which is not visible in the UI). Use this function to retrieve the full details of an individual user.

Endpoint address: /services/rest/user/{id} HTTP method: GET

Request Details

The URL contains the {id} parameter that determines the record to retrieve.

URI Parameters

Parameter Name Mandatory/Optional Value Type Multiple Value Separator (~) Supported? Example

locale

Optional

string

Yes

en_GB~fr

Locale country code.

If used, fields that have language translations have a localeData element returned for the specified locales if data is present.

Example URL

…/services/rest/user/105

Response Details

For a successful response, an HTTP 301 message is returned, which is automatically acted upon to retrieve XML consisting of a userFullDTO root element containing the individual attributes of the requested User record. If an ID is not specified, a list of all users is returned (per the List of Values function).

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 1 - Framework for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

id

HTTP 404 Not found

Invalid {id} - not numeric

id

HTTP 417 IllegalStateException: Cannot find the User to return with id:<###>

Invalid {id} - not found

Retrieve Record by Business Key

Description

Retrieves a single User record's details using its business key (login ID). Use this function to retrieve the full details of an individual user using its Supplier Evaluation login ID.

Endpoint address: /services/rest/byKey/{loginId} HTTP method: GET

Request Details

There are no request parameters, but the URL contains the {loginId} parameter that determines the record to retrieve.

Example URL

…/services/rest/user/byKey/Frank Jones

Response Details

If successful, an HTTP 301 redirect response is sent containing a header Location with the URI of the document requested.

The returned URI represents the call to be made to the Retrieve Record by ID function (with the id substituted with the relevant value), which will return a userFullDTO root element containing the individual attributes of the requested User record.

Note:

If your method of calling the API is configured to automatically follow HTTP 301 redirects, the call may automatically return a userFullDTO root element containing the individual attributes of the requested User record.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 1 - Framework for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

loginId

HTTP 404 Not found

Invalid {loginId} - blank or not found

loginId

HTTP 404 Not found

Invalid {loginId} - not found

Check Record Modification Timestamp

Description

Retrieves the last modification date and time of a User record. Use this function to determine when a user's details were last updated.

Endpoint address: /services/rest/user/{id} HTTP method: HEAD

Request Details

There are no request parameters, but the URL contains the {id} parameter that determines the record to retrieve.

Example URL

…/services/rest/user/105

Response Details

If successful, an HTTP 200 response is sent containing the Last-Modified header showing the date and time of the last update of the requested User record. For example:

HTTP/1.1 200 OK
Date: Wed, 13 Jul 2016 07:52:14 GMT
Last-Modified: Fri, 08 Jul 2016 06:44:46 GMT
Content-Type: application/xml
Content-Length: 0

Error Messages

Element Message Meaning

id

HTTP 417 Expectation Failed

Invalid {id} - not found

id

HTTP 404 Not found

Invalid {id} - not numeric

Create Record

Description

Creates a new User record. Use this function to create a new user in Supplier Evaluation based on data sourced from the external system.

Dependencies: If creating a supplier user, the Supplier must be present in the application and its record ID obtained. For more information, see Dependencies.

Endpoint address: /services/rest/user HTTP method: POST

Request Details

The body of the request contains a UserFullDTO to specify the details of the user to create. Compared to retrieving a user (which uses the same UserFullDTO type), this request is much shorter. Only the attributes that are to be populated on the created User record need to be included. As a minimum, this must include the fields shown in the following table:

Supplier User Mandatory Fields

Field Name Element Name

Name

person / name

Email

person / email

Login Id

code

User Role

role / code

Supplier Code

person / supplier / code

supplier / code

User Type

userType (Fixed value SUPPLIER)

Deleted Record

deleted (Set to false)

Login Id Disabled

disabled (Set to false)

Login Permitted

loginPermitted (Set to true)

Language

language / code

Example Request XML

This example shows the minimum requirement to be able to create a supplier user.

<ns0:userFullDTO xmlns:ns1="http://www.micros.com/creations/core/domain/dto/v1p0/simple" xmlns:ns0="http://www.micros.com/creations/core/domain/dto/v1p0/full">
       <ns0:code>jphillips</ns0:code>
       <ns0:person>
              <ns0:email>jphillips@supplier.co.uk</ns0:email>
              <ns0:name>Jane Phillips</ns0:name>
              <ns0:supplier>
                     <ns1:code>A0174</ns1:code>
              </ns0:supplier>
       </ns0:person>
       <ns0:role>
              <ns1:code>SUPPLIER ADMINISTRATOR</ns1:code>
       </ns0:role>
       <ns0:supplier>
              <ns1:code>A0174</ns1:code>
       </ns0:supplier>
       <ns0:userType>SUPPLIER</ns0:userType>
       <ns0:deleted>false</ns0:deleted>
       <ns0:disabled>false</ns0:disabled>
       <ns0:loginPermitted>true</ns0:loginPermitted>
</ns0:userFullDTO>

Note:

When creating a supplier user, the user type must be set to SUPPLIER. The supplier code must be set to match the required supplier from Supplier Evaluation.

Site User Mandatory Fields

Field Name Element Name

Name

person / name

Email

person / email

Login Id

code

User Role

role / code

Supplier Code

person / supplier / code

supplier / code

Sites

sites / code

sites/ supplierCode

User Type

userType (Fixed value SITE)

Deleted Record

deleted (Set to false)

Login Id Disabled

disabled (Set to false)

Login Permitted

loginPermitted (Set to true)

Language

language / code

Example Request XML

This example shows the minimum requirement to be able to create a site user.

<ns0:userFullDTO xmlns:ns1="http://www.micros.com/creations/core/domain/dto/v1p0/simple" xmlns:ns0="http://www.micros.com/creations/core/domain/dto/v1p0/full">
       <ns0:code>jphillips</ns0:code>
       <ns0:person>
              <ns0:email>sphillips@supplier.co.uk</ns0:email>
              <ns0:name>Sean Phillips</ns0:name>
              <ns0:supplier>
                     <ns1:code>WS0001</ns1:code>
                     <ns1:id>22</ns1:id>
              </ns0:supplier>
       </ns0:person>
       <ns0:role>
              <ns1:code>SUPPLIER ADMINISTRATOR</ns1:code>
       </ns0:role>
       <ns0:sites>
              <ns1:code>WS0001-0001</ns1:code>
              <ns1:id>26</ns1:id>
              <ns1:supplierCode>WS0001</ns1:supplierCode>
              <ns1:id>22</ns1:id>
       </ns0:sites>
       <ns0:supplier>
              <ns1:code>WS0001</ns1:code>
              <ns1:id>22</ns1:id>
       </ns0:supplier>
       <ns0:userType>SITE</ns0:userType>
       <ns0:deleted>false</ns0:deleted>
       <ns0:disabled>false</ns0:disabled>
       <ns0:loginPermitted>true</ns0:loginPermitted>
</ns0:userFullDTO>

Note:

When creating a site user the user type must be set to SITE. The supplier code must be set to match the required supplier from Supplier Evaluation. The site codes must be set to match the required site from Supplier Evaluation.

Retailer User Mandatory Fields

Field Name Element Name

Name

person / name

Email

person / email

Login Id

code

User Role

role / code

Supplier Code

person / supplier / code

supplier / code

(Fixed value RETAILER)

User Type

userType (Fixed value RETAILER)

Deleted Record

deleted (Set to false)

Login Id Disabled

disabled (Set to false)

Login Permitted

loginPermitted (Set to true)

Language

language / code

Example Request XML

This example shows the minimum requirement to be able to create a retailer/portal owner user.

<ns0:userFullDTO xmlns:ns1="http://www.micros.com/creations/core/domain/dto/v1p0/simple" xmlns:ns0="http://www.micros.com/creations/core/domain/dto/v1p0/full">
       <ns0:code>james howard</ns0:code>
       <ns0:person>
              <ns0:email>james.howard@oracle.com</ns0:email>
              <ns0:name>James Howard</ns0:name>
              <ns0:supplier>
                     <ns1:code>RETAILER</ns1:code>
              </ns0:supplier>
       </ns0:person>
       <ns0:role>
              <ns1:code>POWER USER</ns1:code>
       </ns0:role>
       <ns0:supplier>
              <ns1:code>RETAILER</ns1:code>
       </ns0:supplier>
       <ns0:userType>RETAILER</ns0:userType>
       <ns0:deleted>false</ns0:deleted>
       <ns0:disabled>false</ns0:disabled>
       <ns0:loginPermitted>true</ns0:loginPermitted>
</ns0:userFullDTO>

Note:

When creating a retailer/portal owner user, the user type must be set to RETAILER. The supplier code must be set to RETAILER.

Enabling User Accounts

Where the record is linked to another record, such as the Role in these cases, the business key must be provided (not the description) in order to form the link between the records. In general, the business key will be the code attribute of the linked record.

Set loginPermitted to true to ensure a corresponding IDCS or OCI IAM profile is automatically created for the user. If an IDCS or OCI IAM profile is not required, setting the loginPermitted attribute to false will skip the IDCS or OCI IAM profile creation.

Set the deleted attribute to false to ensure the record can be seen in the UI. If omitted, or set to true, it will exist, but will not be visible.

Where the record is linked to another record, such as the Role in these cases, the business key must be provided (not the description) in order to form the link between the records. In general, the business key will be the code attribute of the linked record.

When a new record is created in Supplier Evaluation, a corresponding IDCS or OCI IAM profile is automatically created to manage login authentication. If an IDCS or OCI IAM profile is not required, setting the loginPermitted attribute to false will skip the IDCS or OCI IAM profile creation.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 1 - Framework for details of their mapping to the fields within the Supplier Evaluation UI.

Response Details

For a successful response, an HTTP 200 response is sent with a body containing a UserLink root element. The root element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Newly created User record's internal ID

recordLink

string

URI to the newly created User record, for use in a GET request

loginId

string

Login ID / business key to the newly created User record

name

string

User's name

Error Responses

If the supplied data does not result in a valid User (such as a missing mandatory field), an HTTP 417 response is sent with an ErrorMessage/Message XML body message stating the validation errors. The request should not be reattempted with the same content.

Element Message Meaning

code

ERROR: class

com.micros.creations.core.domain.User.code - The condition is invalid

Code not provided

email

ERROR: class

com.micros.creations.core.domain.User.person.email - The condition is invalid

Email not provided

name

ERROR: class

com.micros.creations.core.domain.User.person.name - The condition is invalid

Name not provided

role

ERROR: class

com.micros.creations.core.domain.User.role - A user must have an active authority profile from either roles or additional authority profiles

Role or authority profiles not provided

Update Record

Description

Updates an existing User record. Use this function to update a user's details in Supplier Evaluation based on data sourced from the external system.

Endpoint address: /services/rest/{id} HTTP method: PUT

Request Details

The body of the request contains a UserFullDTO to specify the updates to the User record. Compared to retrieving a user (which uses the same UserFullDTO type), this request is much shorter. As a minimum, the values specified as mandatory for the Create Record function (see above) must be included.

The request content is similar to that for creating a user. After the call, the User record is updated to match the request.

Note:

When updating records, all values must be included. If a value or element is omitted from the request, the field contents will be cleared on the User record.

Any values passed for Login Id or Email Address are ignored, as they cannot be updated once the record has been created.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 1 - Framework for details of their mapping to the fields within the Supplier Evaluation UI.

Process for Disabling User Accounts

A user's account can be disabled using the Update Record function as follows:

  1. Call the Retrieve Record by Business Key GET function or the Retrieve Record by Id function, passing the login id or the record id respectively, to retrieve the full XML for the user.

  2. Amend the returned XML as follows:

    Set the account to disabled with <ns0:disabled>true<ns0:disabled> and <ns0:loginPermitted>false<ns0:loginPermitted

    Remove the localeData and activeAuthorityProfiles elements.

  3. Call the Update Record PUT function, passing the full amended XML to disable the account.

Response Details

If successful, an HTTP 200 response is sent with a body containing a UserLink element. The UserLink element consists of the returned elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

User record's internal ID

recordLink

string

URI to the User record, for use in a GET request

loginId

string

Login ID/business key to the User record

name

string

User's name

Error Responses

If the supplied data does not result in a valid user (such as a missing mandatory field), an HTTP 417 response is sent with an ErrorMessage/Message XML body message stating the validation errors. The request should not be reattempted with the same content.

SupplierRestService

This section describes the API for managing suppliers. The following functions are available:

Note:

When integrated with Merchandising, using the SupplierRestAPI to make changes that affect the Billing Details table can have an impact on the integration.

List of Values

Description

Retrieves a list of suppliers in a paged list. Use this function to retrieve a simple list of supplier names and IDs, or to locate Supplier record IDs prior to a retrieve or update operation. Parameters are available to apply specific selection criteria for filtering the returned records.

Endpoint address: /services/rest/supplier HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/ Optional Value Type Multiple Value Separator (~) Supported? Wildcard Search Supported? Example
offset Optional int No No 60
pageSize Optional int No No 30
supplierStatus Optional string Yes No AWAITING REGISTRATION
supplierCode Optional string Yes Yes A0001
supplierName Optional string Yes Yes West Road Site
supplierType Optional string Yes Yes AGENT
country Optional string Yes Yes UK
leadBusinessUnit Optional string Yes Yes UK
isActive Optional string No No

true returns active suppliers

no value returns both active and inactive suppliers
modifiedSince Optional string No No 2015-05-19 13:30:39
modifiedUntil Optional string No No 2015-05-19 13:30:39
invoicingRef Optional string No Yes ABC123

Example URLs

…/services/rest/supplier/?offset=2&pageSize=20 …/services/rest/supplier/?supplierStatus=AWAITING REGISTRATION …/services/rest/supplier/?supplierName=API%

Response Details

For a successful response, XML is returned with a SupplierLinkList root element containing an entries element for each matched supplier. The entries element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Supplier record's internal ID

recordLink

string

URI to the SupplierRestService Retrieve record service for this supplier

code

string

Supplier code business key to the Supplier record

name

string

Supplier's name

localName

string

Supplier's name in business language (if used)

The returned XML also contains a totalRecords element, which states the total number of retrievable records that match the filter parameters.

Error Messages

Element Message Meaning

supplierStatus

HTTP 417 IllegalStateException: The Supplier Status <###> does not exist

Invalid supplier status

supplierStatus

HTTP 417 IllegalStateException: The Supplier Statuses <###~###~###> do not exist

Invalid supplier status

supplierType

HTTP 417 IllegalStateException: The Supplier Type <###> does not exist

Invalid supplier type

supplierType

HTTP 417 IllegalStateException: The Supplier Types <###~###> do not exist

Invalid supplier type

country

HTTP 417 IllegalStateException: The Country <###> does not exist

Invalid country

country

HTTP 417 IllegalStateException: The Countries <###~###> do not exist

Invalid country

leadBusinessUnit

HTTP 417 IllegalStateException: The Business Unit <###> does not exist

Invalid business unit

leadBusinessUnit

HTTP 417 IllegalStateException: The Business Units <###~###> do not exist

Invalid business unit

pageSize

Error Code: INVALIDRESTSERVICEPAGESIZE

Page Size must be between 1 and 100

offset

Error Code: INVALIDOFFSET

Offset must be a positive integer

supplierStatus

Error Code: INVALIDSUPPLIERSTATUS

Invalid Supplier Status

supplierType

Error Code: INVALIDSUPPLIERTYPE

Invalid Supplier Type

country

Error Code: INVALIDCOUNTRY

Invalid Country

leadBusinessUnit

Error Code: INVALIDBUSINESSUNIT

Invalid Business Unit

isActive

Error Code: INVALIDBOOLEAN

Invalid isActive value

Permitted values (not case-sensitive) are: true; yes; 1; false; no; 0

Retrieve Record by ID

Description

Retrieves a single Supplier record's details using the record's internal ID (which is not visible in the UI). Use this function to retrieve the full details of an individual supplier.

Endpoint address: /services/rest/supplier/{id} HTTP method: GET

Request Details

The URL contains the {id} parameter that determines the record to retrieve.

URI Parameters

Parameter Name Mandatory/Optional Value Type Multiple Value Separator (~) Supported? Example

locale

Optional

string

Yes

en_GB~fr

Locale country code.

If used, fields that have language translations have a localeData element returned for the specified locales if data is present.

Example URL

…/services/rest/supplier/9

Response Details

For a successful response, an HTTP 301 message is returned, which is automatically acted upon to retrieve XML consisting of a supplierFullDTO root element containing the individual attributes of the requested Supplier record. If an ID is not specified, a list of all suppliers is returned (per the List of Values function).

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

id

HTTP 404 Not Found

Invalid {id} - not numeric

id

HTTP 417 IllegalStateException: Cannot find the Supplier to return with id:<###>

Invalid {id} - not found

Retrieve Record by Business Key

Description

Retrieves a single Supplier record's details using its business key (supplier code). Use this function to retrieve the full details of an individual supplier using the Supplier Evaluation supplier code.

Endpoint address: /services/rest/supplier/byKey/{code} HTTP method: GET

Request Details

There are no request parameters, but the URL contains the {code} parameter that determines the record to retrieve.

Example URL

…/services/rest/supplier/byKey/A0901

Response Details

If successful, an HTTP 301 redirect response is sent containing a header Location with the URI of the document requested.

The returned URI represents the call to be made to the Retrieve Record by ID function (with the id substituted with the relevant value), which will return a supplierFullDTO root element containing the individual attributes of the requested Supplier record.

Note:

If your method of calling the API is configured to automatically follow HTTP 301 redirects, the call may automatically return a supplierFullDTO root element containing the individual attributes of the requested Supplier record.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

code

HTTP 404 Not Found

Invalid {code} - blank

code

HTTP 404 Not Found

Invalid {code}

Check Record Modification Timestamp

Description

Retrieves the last modification date and time of a Supplier record. Use this function to determine when a supplier's details were last updated.

Endpoint address: /services/rest/supplier/{id} HTTP method: HEAD

Request Details

There are no request parameters, but the URL contains the {id} parameter that determines the record to retrieve.

Example URL

…/services/rest/supplier/9

Response Details

If successful, an HTTP 200 response is sent containing the Last-Modified header showing the date and time of the last update of the requested Supplier record.

HTTP/1.1 200 OK
Date: Wed, 13 Jul 2016 07:52:14 GMT
Last-Modified: Fri, 08 Jul 2016 06:44:46 GMT
Content-Type: application/xml
Content-Length: 0

Error Responses

Element Message Meaning

id

HTTP 404 Not Found

Invalid {id} - not numeric

id

HTTP 417 Expectation Failed

Invalid {id} - not found

Create Record

Description

Creates a new Supplier record. Use this function to create new suppliers in Supplier Evaluation based on data sourced from the external system.

Dependencies: Create sites and contacts after creating the supplier. For more information, see Dependencies.

Endpoint address: /services/rest/supplier HTTP method: POST

Request Details

The body of the request contains a SupplierFullDTO to specify the detail of the supplier to create. Compared to retrieving a supplier (which uses the same SupplierFullDTO type), this request is much shorter. Only the attributes that are to be populated on the created Supplier record need to be included. As a minimum, this must include the fields shown in the following table.

Supplier Mandatory Fields

Field Name Element Name

Supplier Name

name

Contact Name

supplierContactName

Email

email

Supplier Type

supplierType/code

Lead Business Unit

businessUnit/code

Billing Code

billingCode/code

Status

Status

Supplier Code Confirmed Flag

supplierCodeConfirmed

Deleted Record

deleted (Set to false)

Created On

createdOn (set to current date using format YYYY-MM-DD or to current date and time using format YYYY-MM-DDThh:mm:ss)

Is Active

isActive - see below

Potential Supplier

potentialSupplier (Set to false)

Example Request XML

This example shows the minimum requirement to be able to create a supplier.

<ns1:supplierFullDTO
    xmlns:ns2="http://www.micros.com/creations/core/domain/dto/v1p0/simple"
    xmlns:ns1="http://www.micros.com/creations/core/domain/dto/v1p0/full">
       <ns1:billingCode>
              <ns2:code>SMALL</ns2:code>
       </ns1:billingCode>
       <ns1:businessUnit>
              <ns2:code>UK</ns2:code>
       </ns1:businessUnit>
       <ns1:email>supplier.contactemail@supplier.co.uk</ns1:email>
       <ns1:name>Name of Supplier</ns1:name>
       <ns1:status>AWAITING REGISTRATION</ns1:status>
       <ns1:supplierContactName>Supplier Contact Name</ns1:supplierContactName>
       <ns1:supplierCodeConfirmed>false</ns1:supplierCodeConfirmed>
       <ns1:supplierType>
              <ns2:code>SUPPLIER_TYPE</ns2:code>
       </ns1:supplierType>
       <ns1:deleted>false</ns1:deleted>
       <ns1:createdOn>2020-09-29T09:00:00</ns1:createdOn>
       <ns1:isActive>false</ns1:isActive>
       <ns1:potentialSupplier>false</ns1:potentialSupplier>
</ns1:supplierFullDTO>

Set the deleted attribute to false to ensure the record can be seen in the UI. If omitted or set to true, it will exist, but will not be visible.

The Supplier API only creates the Supplier record, just as the Site API only creates the Site record. The same goes for the User API; it only creates the User record, and similarly the Contact API only creates the Contacts records. Each Supplier record must also have at least one Site record created for it.

Supplier Contacts and their User records must be created using the respective APIs, and linked to the supplier/site with their record IDs. When a new Supplier is created through the API, the process does not automatically create the initial Supplier user.

Use of the isActive and supplierCodeConfirmed Flags

The isActive and supplierCodeConfirmed flags on the Supplier record are used to control the Registration process within the application UI.

isActive is a Boolean TRUE/FALSE value. It is always FALSE when a Supplier is created in the application UI. If set to FALSE in the API, when the supplier user first logs in to the system, the Supplier Registration wizard runs (as it does if the Supplier has been created through the application UI). Successful completion of the Registration wizard sets the isActive flag to TRUE, thus ensuring it only runs once. Therefore, if set to TRUE in the API, when the Supplier user first logs in to the system, the Registration wizard will not run.

supplierCodeConfirmed is a Boolean TRUE/FALSE value. It is always FALSE when a Supplier is created through the application UI. It is a security measure for the supplier user logging in for the first time, where they are prompted to enter their Supplier Code. The application changes the value to TRUE if there is a successful match.

Setting both isActive and supplierCodeConfirmed as FALSE will trigger the Registration wizard process when the supplier user first logs in, prompting for the entry of the Supplier Code.

Setting both isActive and supplierCodeConfirmed as TRUE indicates that the information captured during the Registration wizard process has effectively been provided, and therefore the wizard will not run.

Setting isActive as FALSE and supplierCodeConfirmed as TRUE indicates that part of the information captured during the Registration wizard process is present, but the wizard will run to allow the user to complete the data entry.

If a Supplier is created with a status of AWAITING AUTHORISATION, but with isActive set as TRUE, the Supplier status is changed to REGISTERED, thus bypassing the Registration process.

Note:

When a new supplier is created manually within the application, the system sends an email to the supplier requesting they complete the registration process. When creating a new supplier through the API, the email is not generated.

Where the record is linked to another record, such as the Supplier Type in this case, the business key must be provided (not the description) in order to form the link between the records. In general, the business key will be the code attribute of the linked record.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Response Details

If successful, an HTTP 200 response is sent with a body containing a SupplierLink root element. The root element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Newly created Supplier record's internal ID

recordLink

string

URI to the newly created Supplier record, for use in a GET request

code

string

Supplier code business key to the newly created Supplier record

name

string

Supplier's name

localName

string

Supplier's name in business language (if used)

Error Messages

If the supplied data does not result in a valid Supplier (such as a missing mandatory field), an HTTP 417 response is sent with an ErrorMessage/Message XML body message stating the validation errors. The request should not be reattempted with the same content.

Element Message Meaning

billingCode

ERROR: class <<hostname>>.Supplier.billingCode - The condition is invalid

No tag provided

billingCode

HTTP 417 IllegalStateException: Cannot locate keyword for class <<hostname>>.BillingCode using code:null

No <ns1:code> tag

billingCode

HTTP 417 IllegalStateException: Cannot locate keyword for class <<hostname>>..BillingCode using code:<###>

Invalid <ns1:code>

businessUnit

ERROR: class <<hostname>>..Supplier.businessUnit - The condition is invalid

No tag provided

businessUnit

HTTP 417 IllegalStateException: Cannot locate keyword for class <<hostname>>..domain.BusinessUnit using code:null

No <ns1:code> tag

businessUnit

HTTP 417 IllegalStateException: Cannot locate keyword for class <<hostname>>..BusinessUnit using code:<###>

Invalid <ns1:code>

code

ERROR: class com.micros.creations.core.domain.Supplier.code - ??Another object exists with this value??

Supplier code already exists

email

ERROR: class com.micros.creations.core.domain.Supplier.email - The condition is invalid

No tag provided

email

ERROR: class <<hostname>>.Supplier.email - The attribute is invalid

Malformed email address

supplierContactName

ERROR: class <<hostname>>.Supplier.supplierContactName - The condition is invalid

No tag provided

supplierContactName

ERROR: class <<hostname>>.Supplier.supplierContactName - The condition is invalid

No value provided

name (supplier name)

ERROR: class <<hostname>>.Supplier.name - The condition is invalid

No tag provided

name (supplier name)

ERROR: class <<hostname>>.Supplier.name - The condition is invalid

No value provided

supplierType

ERROR: class <<hostname>>.Supplier.supplierType - The condition is invalid

No tag provided

supplierType

HTTP 417 IllegalStateException: Cannot locate keyword for class <<hostname>>.SupplierType using code:null

No <ns1:code> tag

supplierType

HTTP 417 IllegalStateException: Cannot locate keyword for class <<hostname>>.SupplierType using code:<###>

Invalid <ns1:code>

Update Record

Description

Updates an existing Supplier record. Use this function to update a supplier's details in Supplier Evaluation based on data sourced from the external system.

Endpoint address: /services/rest/supplier/{id} HTTP method: PUT

Request Details

The body of the request contains a SupplierUpdateDTO to specify the updates to the Supplier record. Compared to retrieving a supplier (which uses the SupplierFullDTO type), this request is much shorter. As a minimum, the values specified as mandatory for the Create Record function (see above) must be included.

The request content is similar to that for creating a supplier, but crucially, the links to other top-level records (Sites, SiteContact, SupplierContact) are omitted. The omission of those ensures that when updating a supplier, only the supplier details need to be specified, and not the details for the related records that may not require updating (and which should be updated to calls to their respective services). After the call, the Supplier record is updated to match the request.

Note:

When updating records, all values must be included. If a value or element is omitted from the request, the field contents will be cleared on the Supplier record (except for the Sites, SiteContacts, and SupplierContacts).

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Response Details

If successful, an HTTP 200 response is sent with a body containing a SupplierLink element. The SupplierLink element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Supplier record's internal ID

recordLink

string

URI to the Supplier record, for use in a GET request

code

string

Supplier code business key to the Supplier record

name

string

Supplier's name

localName

string

Supplier's name in business language (if used)

Error Messages

If the supplied data does not result in a valid Supplier (such as a missing mandatory field), an HTTP 417 response is sent with an ErrorMessage/Message XML body message stating the validation errors. The request should not be reattempted with the same content.

Element Message Meaning

billingCode

HTTP 417 IllegalStateException: Cannot locate keyword for class <<hostname>>.BillingCode using code:<###>

Invalid <ns1:code>

businessUnit

HTTP 417 IllegalStateException: Cannot locate keyword for class <<hostname>>domain.BusinessUnit using code:<###>

Invalid <ns1:code>

code

MySQLIntegrityConstraintViolationException: Duplicate entry <###> for key 'c_code'

Supplier code provided that already exists for another supplier

name

PropertyValueException: not-null property references a null or transient value: <<hostname>>.domain.Supplier.name

No tag provided

status

NullPointerException:

No status tag provided

status

IllegalArgumentException: Empty string is not allowed, should be null on method: <<hostname>>.domain.Supplier@1df35f3[id=<###>,code=<###>]

No status code provided

SiteRestService

This section describes the API for managing sites. The following functions are available:

Note:

When integrated with Merchandising, using the SiteRestAPI to make changes that affect the Billing Details table can have an impact on the integration.

List of Values

Description

Retrieves a list of sites in a paged list. Use this function to retrieve a simple list of supplier names and IDs, or to locate Site record IDs prior to a retrieve or update operation. Parameters are available to apply specific selection criteria for filtering the returned records.

Endpoint address: /services/rest/site HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/ Optional Value Type Multiple Value Separator (~) Supported? Wildcard Search Supported? Example Validation
offset Optional int No No 60  
pageSize Optional int No No 30  
siteStatus Optional string Yes No AWAITING REGISTRATION  
siteCode Optional string Yes Yes A0001-0001  
siteName Optional string Yes Yes West Road Site  
siteType Optional string Yes Yes CANNERY  
country Optional string Yes Yes UK  
businessCategory Optional string Yes Yes CHEESE_DAIRY

Code in the Business Categories glossary at any level of the hierarchy.

Applies the filter to Business Category and Lead Business Category (if used).

Returns a result if any of the values match any of the specification's business categories.
businessUnit Optional string Yes Yes UK
supplierName Optional string Yes Yes ABC Ltd
supplierActive Optional String No No

true

(otherwise will return active and inactive suppliers)
modifiedSince Optional string No No 2015-05-19 13:30:39
modifiedUntil Optional string No No 2015-05-19 13:30:39
statusChangedFrom Optional string No No 2015-06-10 09:00:00

If From and Until are both used, then the Until date must be greater than or equal to the From date.
statusChangedUntil Optional string No No 2015-06-10 09:00:00
statusChangedTo Optional string Yes No ACTIVE
leadTechnologist Optional string Yes Yes John Smith The user's Login Id.

Example URLs

…/services/rest/site/?offset=2&pageSize=20 …/services/rest/site/?siteStatus=ACTIVE …/services/rest/site/?supplierName=API%

Response Details

For a successful response, XML is returned with a SiteLinkList root element containing an entries element for each matched site. The entries element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Site record's internal ID

recordLink

string

URI to the SiteRestService Retrieve record for this site

code

string

Site code business key to the Site record

name

string

Site's name

localName

string

Site's name in business language (if used)

The returned XML also contains a totalRecords element, which states the total number of retrievable records that match the filter parameters.

Error Messages

Element Message Meaning

siteStatus

HTTP 417 IllegalStateException: The Supplier Status <###> does not exist

Invalid site status

siteStatus

HTTP 417 IllegalStateException: The Supplier Statuses <###~###~###> do not exist

Invalid site status

siteType

HTTP 417 IllegalStateException: The Supplier Type <###> does not exist

Invalid supplier type

siteType

HTTP 417 IllegalStateException: The Supplier Types <###~###> do not exist

Invalid supplier type

country

HTTP 417 IllegalStateException: The Country <###> does not exist

Invalid country

country

HTTP 417 IllegalStateException: The Countries <###~###> do not exist

Invalid country

businessCategory

HTTP 417 IllegalStateException: The Business Category <###> does not exist

Invalid business category

businessCategory

HTTP 417 IllegalStateException: The Business Categories <###~###> do not exist

Invalid business category

businessUnit

HTTP 417 IllegalStateException: The Business Unit <###> does not exist

Invalid business unit

businessUnit

HTTP 417 IllegalStateException: The Business Units <###~###> do not exist

Invalid business unit

modifiedSince

Invalid dates cause stack trace to come back to "response"

modifiedUntil

Invalid dates cause stack trace to come back to "response"

pageSize

Error Code: INVALIDRESTSERVICEPAGESIZE INVALIDPAGESIZE

Page Size must be between 1 and 100

offset

Error Code: INVALIDOFFSET

Offset must be a positive integer

siteStatus

Error Code: INVALIDSITESTATUS INVALIDSITESTATUSES

Invalid Site Status

siteType

Error Code: INVALIDSITETYPE

Invalid Site Type

country

Error Code: INVALIDCOUNTRY

Invalid Country

businessCategory

Error Code: INVALIDBUSINESSCATEGORY

Invalid Business Category

businessUnit

Error Code: INVALIDBUSINESSUNIT

Invalid Business Unit

supplierActive

Error Code: INVALIDBOOLEAN

Invalid supplierActive value

Permitted values (not case-sensitive) are: true; yes; 1; false; no; 0

leadTechnologist

Error Code: INVALIDUSER

Invalid Lead Technologist

statusChangedFrom

Error Code: INVALIDDATEFORMAT

Invalid Status Changed From

Must be a valid date/time format:

Year-Month-DayOfMonth Hour:Minute:Seconds

such as 2016-12-30 09:59:59

statusChangedUntil

Error Code: INVALIDDATEFORMAT

Invalid Status Changed Until

Must be a valid date/time format:

Year-Month-DayOfMonth Hour:Minute:Seconds

such as 2016-12-30 09:59:59

statusChangedTo

Error Code: INVALIDSTATUSCHANGEDTO

Either Status Changed From or Status Changed Until must be specified if filtering on Status Changed To

Retrieve Record by ID

Description

Retrieves a Site record's details using the record's internal unique ID (which is not visible in the UI). Use this function to retrieve the full details of an individual site.

Endpoint address: /services/rest/site/{id} HTTP method: GET

Request Details

The URL contains the {id} parameter that determines the record to retrieve.

URI Parameters

Parameter Name Mandatory/Optional Value Type Multiple Value Separator (~) Supported? Example

locale

Optional

string

Yes

en_GB~fr

Locale country code.

If used, fields that have language translations have a localeData element returned for the specified locales if data is present.

Example URL

…/services/rest/site/87

Response Details

For a successful response, an HTTP 301 message is returned, which is automatically acted upon to retrieve XML consisting of a siteFullDTO root element containing the individual attributes of the requested Site record. If an ID is not specified, a list of all sites is returned (per the List of Values function).

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

id

HTTP 404 Not Found

Invalid {id} - not numeric

id

HTTP 417 IllegalStateException: Cannot find the Site to return with id:<###>

Invalid {id} - not found

Retrieve Record by Business Key

Description

Retrieves a single Site record's details using its business key (supplier and codes). Use this function to retrieve the full details of an individual site using the combination of the Supplier Evaluation supplier and site codes.

Endpoint address: /services/rest/site/byKey/{supplierCode}/{siteCode} HTTP method: GET

Request Details

There are no request parameters, but the URL contains the {supplierCode} and {siteCode} parameters that determine the record to retrieve.

Example URL

…/services/rest/site/byKey/A0001/A0001-0001

Response Details

If successful, an HTTP 301 redirect response is sent containing a header Location with the URI of the document requested.

The returned URI represents the call to be made to the Retrieve Record by ID function (with the id substituted with the relevant value), which will return a siteFullDTO root element containing the individual attributes of the requested Site record.

Note:

If your method of calling the API is configured to automatically follow HTTP 301 redirects, the call may automatically return a siteFullDTO root element containing the individual attributes of the requested Site record.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

supplierCode

HTTP 404 Not Found

Invalid {supplierCode} - blank

siteCode

HTTP 404 Not Found

Invalid {siteCode}

Check Record Modification Timestamp

Description

Retrieves the last modification date and time of a Site record. Use this function to determine when a site's details were last updated.

Endpoint address: /services/rest/site/{id} HTTP method: HEAD

Request Details

There are no request parameters, but the URL contains the {id} parameter that determines the record to retrieve.

Example URL

…/services/rest/site/87

Response Details

If successful, an HTTP 200 response is sent containing the Last-Modified header showing the date and time of the last update of the requested Site record.

HTTP/1.1 200 OK
Date: Wed, 13 Jul 2016 07:52:14 GMT
Last-Modified: Fri, 08 Jul 2016 06:44:46 GMT
Content-Type: application/xml
Content-Length: 0

Error Messages

Element Message Meaning

id

HTTP 404 Not Found

Invalid {id} - not numeric

id

HTTP 417 Expectation Failed

Invalid {id} - not found

Create Record

Description

Creates a new Site record. Use this function to create new sites in Supplier Evaluation based on data sourced from the external system.

Dependencies: The Supplier must be present in the application and its record ID obtained. If assigning a Business Category or Technologist, the record must be present in the application and its record ID obtained. Create Contacts after creating the Site. For more information, see Dependencies.

Endpoint address: /services/rest/site HTTP method: POST

Request Details

The body of the request contains a SiteFullDTO element to specifying the details of the site to create. Compared to retrieving a site (which uses the same SiteFullDTO type), this request is much shorter. Only the attributes that are to be populated on the created Site record need to be included. As a minimum, this must include the fields shown in the following table.

Site Mandatory Fields

Field Name Element Name

Site Name

name

Site Type

siteType/code

Categories

businessCategories

Lead Technologist

leadTechnicalManager

Supplier

supplier/code

Site Status

siteStatus

Deleted Record

deleted (Set to false)

Example Request XML

This example shows the minimum requirement to be able to create a site against a supplier.

<ns1:siteFullDTO
    xmlns:ns1="http://www.micros.com/creations/core/domain/dto/v1p0/simple"
    xmlns:ns0="http://www.micros.com/creations/core/domain/dto/v1p0/full">

       <ns0:businessCategories>
              <ns1:code>CATEGORY2A</ns1:code>
       </ns0:businessCategories>
       <ns0:leadTechnicalManager>
              <ns1:code>techadmin</ns1:code>
       </ns0:leadTechnicalManager>
      
       <ns0:name>Site Name</ns0:name>
       <ns0:siteType>
              <ns1:code>SITE_TYPE_EXAMPLE</ns1:code>
       </ns0:siteType>
       <ns0:siteStatus>
              <ns1:status>ACTIVE</ns1:status>
       </ns0:siteStatus>
       <ns0:supplier>
              <ns1:code>WS0001</ns1:code>
       </ns0:supplier>
       <ns0:deleted>false</ns0:deleted>

</ns1:siteFullDTO>

Set the deleted attribute to false to ensure the record can be seen in the UI. If omitted or set to true, it will exist, but will not be visible.

Where the record is linked to another record, such as the Site Type in this case, the business key must be provided (not the description) in order to form the link between the records. In general, the business key will be the code attribute of the linked record.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Response Details

If successful, an HTTP 200 response is sent with a body containing a SiteLink root element containing the site data, and a SupplierLink element, consisting of the parent supplier data. The returned elements are shown in the following table.

Returned Elements

Element Type Description

recordId

long

Newly created Site record's internal ID

recordLink

string

URI to the newly created Site record, for use in a GET request

code

string

Supplier and site code business key to the newly created Site record

name

string

Site's name

localName

string

Site's name in business language (if used)

supplierLink/recordId

long

Newly created site's Supplier record internal ID

supplierLink/recordLink

string

URI to the newly created site's Supplier record, for use in a GET request

recordLink/code

string

Supplier code business key to the newly created site's Supplier record

recordLink/name

string

Supplier's name

recordLink/localName

string

Supplier's name in business language (if used)

Error Messages

If the supplied data does not result in a valid Site (such as a missing mandatory field), an HTTP 417 response is sent with an ErrorMessage/Message XML body message stating the validation errors. The request should not be reattempted with the same content.

Element Message Meaning

supplier/id

Null Pointer Exception

Supplier ID not provided

supplier/id

No row with the given identifier exists: [com.micros.creations.core.domain.Supplier#<###>]

Supplier not found

siteStatus

Null Pointer Exception

Site Status not provided

siteStatus

Cannot locate keyword for class com.micros.creations.core.domain.SiteStatus using status:<###>

Site Status not found

siteType

ERROR: class com.micros.creations.core.domain.Site.siteType - The condition is invalid

Site Type not provided

siteType

Cannot locate keyword for class com.micros.creations.core.domain.SiteType using code:<###>

Site Type not found

name

class com.micros.creations.core.domain.Site.name - The condition is invalid

Site name not provided

leadTechnicalManager

ERROR: class com.micros.creations.core.domain.Site.leadTechnicalManager - The condition is invalid

Lead Technical Manager not provided

leadTechnicalManager

HTTP 417 IllegalStateException: Cannot locate keyword for class com.micros.creations.core.domain.User using code:<###>

Lead Technical Manager not found

businessCategories

ERROR: class com.micros.creations.core.domain.Site.businessCategories - The condition is invalid

Business Category not provided

businessCategories

Cannot locate keyword for class com.micros.creations.core.domain.BusinessCategory using code:<###>

Business Category not found

code

Duplicate site code

The site already exists for this supplier

Update Record

Description

Updates an existing Site record. Use this function to update a site's details in Supplier Evaluation based on data sourced from the external system.

Endpoint address: /services/rest/site/{id} HTTP method: PUT

Request Details

The body of the request contains a SiteUpdateDTO to specify the updates to the Site record. Compared to retrieving a site (which uses the SiteFullDTO type), this request is much shorter. As a minimum, the values specified as mandatory for the Create Record function (see above) must be included.

The request content is similar to that for creating a site, but crucially, the links to other top-level records (SiteContact) are omitted. The omission of those ensures that when updating a site, only the site details need to be specified, and not the details for the related records that may not require updating (and which should be updated with calls to their respective services). After the call, the Site record is updated to match the request

Note:

When updating records, all values must be included. If a value or element is omitted from the request, the field contents will be cleared on the Site record (except for the SiteContacts).

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Response Details

If successful, an HTTP 200 response is sent with a body containing a SiteLink root element containing the site data, and a SupplierLink element, consisting of the parent supplier data. The returned elements are shown in the following table.

Returned Elements

Element Type Description

recordId

long

Updated Site record's internal ID

recordLink

string

URI to the updated Site record, for use in a GET request

code

string

Site code business key to the updated Site record

name

string

Site's name

localName

string

Site's name in business language (if used)

supplierLink/recordId

long

Updated site's Supplier record internal ID

supplierLink/recordLink

string

URI to the updated site's Supplier record, for use in a GET request

recordLink/code

string

Supplier code business key to the updated site's Supplier record

recordLink/name

string

Supplier's name

recordLink/localName

string

Supplier's name in business language (if used)

Error Responses

If the supplied data does not result in a valid Site (such as a missing mandatory field), an HTTP 417 response is sent an with an ErrorMessage/Message XML body message stating the validation errors. The request should not be reattempted with the same content.

ContactRestService

This section describes the API for managing supplier and site contacts. The following functions are available:

List of Values

Description

Retrieves a list of contacts in a paged list. Use this function to retrieve a simple list of contact names and IDs, or to locate Contact record IDs prior to a retrieve or update operation. Parameters are available to apply specific selection criteria for filtering the returned records.

Endpoint address: /services/rest/contact HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/ Optional Value Type Multiple Value Separator (~) Supported? Wildcard Search Supported? Example
offset Optional int No No 60
pageSize Optional int No No 30
name Optional string Yes Yes John Smith
supplierContactRoles Optional string Yes Yes HEAD OF MANUFACTURING
siteContactRoles Optional string Yes Yes HEAD OF MANUFACTURING
country Optional string Yes Yes UK
selectedSites Optional string No No A0001-0001
supplierCode Optional string Yes Yes A0001
supplierName Optional string Yes Yes ABC Ltd.
siteStatus Optional string Yes No ACTIVE~INACTIVE
supplierActive Optional string No No

true returns active contacts

no value returns both active and inactive contacts
modifiedSince Optional string No No 2015-05-19 13:30:39
modifiedUntil Optional string No No 2015-05-19 13:30:39

Example URLs

…/services/rest/contact/?offset=2&pageSize=20 …/services/rest/contact/?siteStatus=ACTIVE …/services/rest/contact/?supplierName=API%

Response Details

For a successful response, XML is returned with a ContactLinkList root element containing an entries element for each matched contact. The entries element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Contact record's internal ID

recordLink

string

URI to the ContactRestService Retrieve record service for this contact

email

string

Contact's email address

name

string

Contact's name

siteContact

Boolean

Indicates if a contact for the site (true), else false

supplierContact

Boolean

Indicates if a contact for the supplier (true), else false

The returned XML also contains a totalRecords element, which states the total number of retrievable records that match the filter parameters.

Error Messages

Element Message Meaning

supplierContactRoles

HTTP 417 IllegalStateException: The Supplier Contact Role <###> does not exist

Invalid supplier contact role

supplierContactRoles

HTTP 417 IllegalStateException: The Supplier Contact Roles <###~###> do not exist

Invalid supplier contact role

siteContactRoles

HTTP 417 IllegalStateException: The Site Contact Role <###> does not exist

Invalid site contact role

siteContactRoles

HTTP 417 IllegalStateException: The Site Contact Roles <###~###> do not exist

Invalid site contact role

country

HTTP 417 IllegalStateException: The Country <###> does not exist

Invalid country code

country

HTTP 417 IllegalStateException: The Countries <###~###> do not exist

Invalid country code

siteStatus

HTTP 417 IllegalStateException: The Supplier Status <###> does not exist

Invalid supplier status code

pageSize

Error Code: INVALIDRESTSERVICEPAGESIZE INVALIDPAGESIZE

Page Size must be between 1 and 100

offset

Error Code: INVALIDOFFSET

Offset must be a positive integer

supplierContactRole

Error Code: INVALIDCONTACTROLE

Invalid Supplier Contact Role

siteContactRole

Error Code: INVALIDCONTACTROLE

Invalid Site Contact Role

country

Error Code: INVALIDCOUNTRY

Invalid Country

selectedSite

Error Code: INVALIDSITE

Invalid Site

supplierCode

Error Code: INVALIDSUPPLIER

Invalid Supplier

siteStatus

Error Code: INVALIDSITESTATUS

Invalid Site Status

supplierActive

Error Code: INVALIDBOOLEAN

Invalid supplierActive value

Permitted values (not case-sensitive) are: true; yes; 1; false; no; 0

Retrieve Record by ID

Description

Retrieves a single Contact record's details using the record's unique ID. Use this function to retrieve the full details of an individual supplier or site contact.

Endpoint address: /services/rest/contact/{id} HTTP method: GET

Request Details

The URL contains the {id} parameter that determines the record to retrieve.

URI Parameters

Parameter Name Mandatory/Optional Value Type Multiple Value Separator (~) Supported? Example

locale

Optional

string

Yes

en_GB~fr

Locale country code.

If used, fields that have language translations have a localeData element returned for the specified locales if data is present.

Example URL

…/services/rest/contact/405

Response Details

For a successful response, an HTTP 301 message is returned, which is automatically acted upon to retrieve XML consisting of a contactAndPersonDTO root element containing the individual attributes of the requested Contact record and the person it associates to.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

id

HTTP 404 Not Found

Invalid {id} - not numeric

id

HTTP 417 IllegalStateException: Cannot find the Contact to return with id:<###>

Invalid {id} - not found

Retrieve Supplier Contact Record by Business Key

Description

Retrieves a single Supplier Contact record's details using its business key (supplier code, contact name, and email address). Use this function to retrieve the full details of an individual supplier contact using the combination of the Supplier Evaluation supplier codes, name of the contact, and the contact's email address.

Endpoint address: /services/rest/contact/byKey/supplier/{supplierCode}/{name}/{email} HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/Optional Value Type Multiple Value Separator (~) Supported? Example

supplierCode

Mandatory

string

No

A0001

name

Mandatory

string

No

John Doe

email

Mandatory

string

No

john.doe@email.com

Example URL

…/services/rest/contact/byKey/supplier/A0001/John Doe/john.doe@email.com

Response Details

If successful, an HTTP 301 redirect response is sent containing a header Location with the URI of the document requested.

The returned URI represents the call to be made to the Retrieve Record by ID function (with the id substituted with the relevant value), which will return a contactAndPersonDTO root element containing the individual attributes of the requested Contact record.

Note:

If your method of calling the API is configured to automatically follow HTTP 301 redirects, the call may automatically return a contactAndPersonDTO root element containing the individual attributes of the requested Contact record.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Error Responses

In the document cannot be located, an HTTP 404 response is sent.

Retrieve Site Contact Record by Business Key

Description

Retrieves a single Site Contact record's details using its business key (supplier code, site code, contact name, and contact email). Use this function to retrieve the full details of an individual site contact using the combination of the Supplier Evaluation supplier and site codes, name of the contact, and the contact's email address.

Endpoint address: /services/rest/contact/byKey/site/{supplierCode}/{siteCode}/{name}/{email} HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/Optional Value Type Multiple Value Separator (~) Supported? Example

supplierCode

Mandatory

string

No

A0001

siteCode

Mandatory

string

No

A0001-0001

name

Mandatory

string

No

John Doe

email

Mandatory

string

No

john.doe@email.com

Example URL

…/services/rest/contact/byKey/site/A0001/A0001-0001/ John Doe/john.doe@email.com

Response Details

For a successful response, XML is returned with a contactAndPersonDTO root element containing the individual attributes of the requested Contact record and the person it associates to.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Error Responses

In the document cannot be located, an HTTP 404 response is sent.

Check Record Modification Timestamp

Description

Retrieves the last modification date and time of a Contact record. Use this function to determine when a supplier or site contact's details were last updated.

Endpoint address: /services/rest/contact/{id} HTTP method: HEAD

Request Details

There are no request parameters, but the URL contains the {id} parameter that determines the record to retrieve.

Example URL

…/services/rest/contact/405

Response Details

If successful, an HTTP 200 response is sent containing the Last-Modified header to show the last modification date and time of the last update of the requested Contact record.

HTTP/1.1 200 OK
Date: Wed, 13 Jul 2016 07:52:14 GMT
Last-Modified: Fri, 08 Jul 2016 06:44:46 GMT
Content-Type: application/xml
Content-Length: 0

Error Messages

Element Message Meaning

id

HTTP 404 Not Found

Invalid {id} - not numeric

id

HTTP 417 Expectation Failed

Invalid {id} - not found

Create Record

Description

Creates a new Contact record (and the associated Person record). Use this function to create new supplier or site contacts in Supplier Evaluation based on data sourced from the external system.

Dependencies: The Supplier (and Site, if a site contact) must be present in the application and its record ID obtained. Omit the Site element if not a site contact. The User/Person must be present in the application and its record ID obtained. For more information, see Dependencies.

Endpoint address: /services/rest/contact HTTP method: POST

Request Details

The body of the request contains a ContactAndPersonDTO to specify the details of the contact to create. Compared to the retrieving a contact (which uses the same ContactAndPersonDTO type), this request is much shorter. Only the attributes that are to be populated on the created Contact record need to be included. As a minimum, this must include the fields shown in the following table.

Contact Mandatory Fields

Field Name Element Name

Name

contactFullDTO/person/name

personFullDTO/name

User Id

contactFullDTO/person/id

Supplier

contactFullDTO/person/supplier/id

contactFullDTO/company/code

personFullDTO/supplier/code

personFullDTO/supplier/id

Email

contactFullDTO/person/email

personFullDTO/email

Phone

contactFullDTO/contactDetails/phoneNumber

Supplier Contact Roles

contactFullDTO/supplierContactRole/code

Contact Type

contactFullDTO/dtype

Site Contact Flag

contactFullDTO/siteContact

Supplier Contact Flag

contactFullDTO/supplierContact

Deleted Record

deleted (Set to false)

Example Request XML

This example shows the minimum requirement to be able to create a contact against a supplier.

<ns0:ContactAndPersonDTO xmlns:ns4="http://www.oracle.com/orsecs/service/rest/model" xmlns:ns0="http://www.micros.com/creations/core/domain/dto/v1p0/full" xmlns:ns1="http://www.micros.com/creations/core/domain/dto/v1p0/simple">
       <ns0:contactFullDTO>
              <ns0:contactDetails>
                     <ns0:phoneNumber>01234 56789</ns0:phoneNumber>
              </ns0:contactDetails>
              <ns0:dtype>SupplierContact</ns0:dtype>
              <ns0:person>
                     <ns1:email>jphillips@example.com</ns1:email>
                     <ns1:name>Jane Phillips</ns1:name>
                     <ns1:supplier>
                            <ns1:code>A0001</ns1:code>
                     </ns1:supplier>
              </ns0:person>
              <ns0:siteContact>false</ns0:siteContact>
              <ns0:supplierContact>true</ns0:supplierContact>
              <ns0:supplierContactRole>
                     <ns1:code>ACCOUNT MANAGER</ns1:code>
              </ns0:supplierContactRole>
              <ns0:company>
                     <ns1:code>A0001</ns1:code>
              </ns0:company>
       </ns0:contactFullDTO>
       <ns0:personFullDTO>
              <ns0:email>jphillips@example.com</ns0:email>
              <ns0:name>Jane Phillips</ns0:name>
              <ns0:supplier>
                     <ns1:code>A0001</ns1:code>
              </ns0:supplier>
       </ns0:personFullDTO>
       <ns0:deleted>false</ns0:deleted>
</ns0:ContactAndPersonDTO>

Set the deleted attribute to false to ensure the record can be seen in the UI. If omitted or set to true, it will exist, but will not be visible.

If a contact has multiple supplier or site contact roles, they should be separate entries as follows:

<ns0:supplierContactRole>
       <ns1:code>ACCOUNT MANAGER</ns1:code>
</ns0:supplierContactRole>
<ns0:supplierContactRole>
       <ns1:code>AUDITS AND VISITS CONTACT</ns1:code>
</ns0:supplierContactRole>
<ns0:supplierContactRole>
       <ns1:code>EMERGENCY CONTACT</ns1:code>
</ns0:supplierContactRole>

Where the record is linked to another record, such as the Contact Role in this case, the business key must be provided (not the description) in order to form the link between the records. In general, the business key will be the code attribute of the linked record.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Response Details

If successful, an HTTP 200 response is sent with a body containing a ContactLink root element. The root element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Newly created Contact record's internal ID

recordLink

string

URI to the newly created Contact record, for use in a GET request

email

string

Email address of the newly created contact

name

string

Contact's name

siteContact

Boolean

Indicates if a contact for the site (true), else false

supplierContact

Boolean

Indicates if a contact for the supplier (true), else false

Error Messages

Element Message Meaning

phoneNumber

phoneNumber - The condition is invalid

Missing tag

dtype

IllegalArgumentException: Invalid value for dtype:<###>

Invalid value

SupplierContact; SiteContact

name & email

HTTP 417 IllegalStateException: Cannot locate Person record with name: <###> and email: <###>

A valid user must be found with matching name and email address

company

HTTP 417 IllegalStateException: Cannot locate keyword for class com.micros.creations.core.domain.Company using code:<###>

Invalid company/supplier code

Update Record

Description

Updates an existing Contact record. Use this function to update a supplier or site contact's details in Supplier Evaluation based on data sourced from the external system.

Endpoint address: /services/rest/contact/{id} HTTP method: PUT

Request Details

The body of the request contains a ContactAndPersonDTO element to specify the updates to the Contact record. As a minimum, the values specified as mandatory for the Create Record function (see above) must be included.

The request content is the same as that for creating a contact. After the call, the Contact record is updated to match the request.

Note:

When updating records, all values must be included. If a value or element is omitted from the request, the field contents will be cleared on the Contact record.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Response Details

If successful, an HTTP 200 response is sent with a body containing a ContactLink element. The ContactLink element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Contact record's internal ID

recordLink

string

URI to the Contact record, for use in a GET request

email

string

Contact's email address

name

string

Contact's name

siteContact

Boolean

Indicates if a contact for the site (true), else false

supplierContact

Boolean

Indicates if a contact for the supplier (true), else false

Error Messages

If the supplied data does not result in a valid Contact (such as a missing mandatory field), an HTTP 417 response is sent with an ErrorMessage/Message XML body message stating the validation errors. The request should not be reattempted with the same content.

TaskRestService

This section describes the API for managing user tasks. The following function is available:

List of Tasks

Description

Retrieves a list of tasks for a user in the given language. Use this function to retrieve a list of a specific user's entries in their Supplier Evaluation Task Manager app. Parameters are used to specify the name of the user, and the language of the returned task details.

Endpoint address: /services/rest/task HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/ Optional Value Type Multiple Value Separator (~) Supported? Wildcard Search Supported? Example
userId Mandatory string No No John Smith
language Mandatory string No No en_GB

Example URL

…/services/task/?language=en_GB

The userId parameter is the login ID of the user for which the tasks list is to be retrieved. The language parameter is the code of the language record/locale in which to retrieve the task details.

Response Details

For a successful response, XML is returned with a TaskDTOList root element containing a tasks element for each matched task. The root element consists of the elements in the following table.

Returned Elements

Element Type Description

message

string

Name of the task, in the language specified

messageId

string

A language-agnostic identifier for the task

myCreationsLink

string

A URI to the Supplier Evaluation system, which will open the list of items for that task

taskItemCount

int

The number of items in the task

Error Messages

Element Message Meaning

userId

userId required

User not provided

userId

Cannot find user with login id <###>

User not found

language

language required

Language not provided

language

Invalid locale format: <###>

Language not found

UrgentItemsRestService

This section describes the API for retrieving a count of a user's urgent items. The following function is available:

Number of Urgent Items

Description

Retrieves a count of the number of Urgent Item tasks for a user. Use this function to determine the number of pending urgent tasks a specific user has in their Supplier Evaluation Urgent Item Manager app. A parameter is passed to specify the name of the user.

Endpoint address: /services/rest/urgentItems HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/ Optional Value Type Multiple Value Separator (~) Supported? Wildcard Search Supported? Example
userId Mandatory string No No John Smith

The userId parameter is the login ID of the user for which the number of pending urgent items are to be retrieved.

Response Details

For a successful response, XML is returned with an UrgentItemsModel root element containing an itemCount element that specifies the number of Urgent Items.

Error Messages

Element Message Meaning

userId

User not provided: userId required

User not provided

userId

Cannot find user with login id <###>

User not found

ArtworkRestService

This section describes the API for Artwork integration. The following functions are available:

Started Activities

Description

Retrieves a list of Project Activities that have their useMyArtwork flag set, and their status has changed to Started within the specified date range. This function is used for the integration of Supplier Evaluation with an external Artwork Management system.

Endpoint address: /services/rest/artwork/started HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/ Optional Value Type Multiple Value Separator (~) Supported? Wildcard Search Supported? Example
offset Optional int No No 60
pageSize Optional int No No 30
fromDate Mandatory string No No 2014-12-30 23:59:59
toDate Mandatory string No No 2015-12-30 23:59:59

Response Details

For a successful response, XML is returned with a CreateArtworkRequestList root element containing an entries element for each matching Artwork project activity. A totalRecords element identifies the number of records returned. Separate activityDetails and project elements group the returned activity and project data. The elements consist of the elements in the following tables.

Returned Elements - activityDetails

Element Type Description

activityName

string

Project activity's title

activityRecordId

long

Project activity record's internal ID

actualStartDate

string

Actual start date of the project activity

checkpointOnly

Boolean

Is the project activity a checkpoint only type

criticalPath

Boolean

Is the project activity a critical path type

duration

int

Duration of the project activity

isAutoGate

string

Project's type of auto gate

isGate

Boolean

Is the project activity a gate type

isKey

Boolean

Is the project activity a key type

projectId

long

Project record's internal ID

projectTitle

string

Project's title

proposedEndDate

string

Proposed end date of the project activity

proposedStartDate

string

Proposed start date of the project activity

responsibleUserRoles

string

Role names of the responsible users

sequenceNumber

string

Project activity's sequence number

statusCode

string

Code of the project activity's status

subStatusCode

string

Code of the project activity's sub-status

Returned Elements - projects

Element Type Description

brand

string

Name of the project's brand

categories

string

Names of the project's categories (the lowest level of the selected category - may be multiples)

masterProject

Boolean

If the project is a master type

newCategoryComments

string

Category comments

packaging

string

Packaging details

productRangeInformation

string

Project’s product range details

projectConcept

string

Project's business key ID

projectId

string

Project's business key ID

projectManager

string

Name of the project's project manager

projectRecordId

long

Project record's internal ID

projectTitle

string

Project's title

projectType

string

Type of project

proposedProducts

string

Project's proposed products

specType

string

Type of project's product specification

status

string

Status of the project

subBrand

string

Name of the project's sub-brand

supplier

string

Name of the supplier associated to the project

site

string

Name of the site associated with the project

targetConsumer

string

Project's target consumer details

teamDetails/role

string

Name of the team role

teamDetails/users

string

Name of the team users

templateFolder

string

Name of the project template folder

templateType

string

Type of the project's template

templateUsed

string

Name of the project's template

Error Messages

Element Message Meaning

fromDate

fromDate parameter required

From date not provided

toDate

toDate parameter required

To date not provided

fromDate

fromDate and toDate parameters are required

From and To dates not provided

toDate

From date must be before or equal to To date

From date is after To date

fromDate

HTTP 417 <errorMessage>

Not a valid date, whereby <errorMessage> will identify the issue

For example: IllegalInstantException: Cannot parse "2018-03-25 01:00:00": Illegal instant due to time zone offset transition (Europe/London) In this example, due to the clocks

In this example, due to the clocks moving forward (in the server's time-zone), the passed in date is invalid

toDate

HTTP 417 <errorMessage>

Not a valid date, whereby <errorMessage> will identify the issue (see example above)

Update Record

Description

Updates the sub-status of existing Artwork Project Activities. This function is used for the integration of Supplier Evaluation with an external Artwork Management system, to update the status of an Artwork activity from the external system.

Endpoint address: /services/rest/artwork/update HTTP method: POST

Request Details

The body of the request contains an activityUpdateRequest element consisting of the elements shown in the following table.

Request Elements

Element Type Description

activityName

string

Project activity's name

activityRecordId

long

Project activity record's internal ID

projectId

string

ID business key to the Project record

projectRecordId

long

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 WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 3 - Process for details of their mapping to the fields within the Supplier Evaluation UI.

Response Details

If successful, an HTTP 200 response is sent with a body containing an ArtworkActivityLink element. The ArtworkActivityLink element consists of the elements shown in the following table.

Returned Elements

If successful, an HTTP 200 response is sent.

Element Type Description

recordId

long

Project activity's internal ID

recordLink

string

URI to the Product Activity record, for use in a GET request

code

string

Code business key to the Project Activity record

title

string

Project activity's title

Error Messages

In the event that an error occurs, an HTTP 500 response is sent.

The following conditions may prevent a successful update:

  • An invalid project record id or activity record id.

  • The activity sub-statuses not being configured in Supplier Evaluation (including the general sub-statuses COMPLETED, MESSAGE SENT, MESSAGE ACCEPTED, and MESSAGE FAILED).

  • The activity's template not being flagged as an artwork type, or having the permitted activity sub-statuses assigned, prior to the activity being created (a snapshot of the template settings is stored on the Activity record on creation).

BusinessCategoryService

This section describes the API for managing Business Categories. The following functions are available:

List of Values

Description

Retrieves a list of categories in a paged list. Use this function to retrieve a simple list of categories and IDs, or to locate Business Category record IDs prior to a retrieve or update operation. Parameters are available to apply specific selection criteria for filtering the returned records.

Endpoint address: /services/rest/businessCategory HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/ Optional Value Type Multiple Value Separator (~) Supported? Wildcard Search Supported? Example
offset Optional int No No 60
pageSize Optional int No No 30
code Optional string Yes Yes POTATOES_LOOSE
parentCode Optional string Yes Yes POTATOES
entityDescription Optional string Yes Yes Loose Potatoes
specificationType Optional string Yes No FOOD~PRODUCE
topLevelCategory Optional Boolean No No TRUE
modifiedSince Optional string No No 2015-05-19 13:30:39
modifiedUntil Optional string No No 2015-05-19 13:30:39

Example URLs

…/services/rest/businessCategory/?offset=2&pageSize=20 …/services/rest/businessCategory/?code=POTATOES_LOOSE …/services/rest/businessCategory/?entityDescription=Potato%

The code parameter will attempt to find a single category with a matching code. The parentCode parameter will find any categories whose parent has the given code.

The entityDescription matches any category whose description (irrespective of language) matches the value given; this is just the description of the category in question and does not include those of parents.

The specificationType parameter is a tilde (~) separated list of types.

Note:

Including a value in the specificationType filter will exclude any categories for which no specification type has been selected.

The topLevelCategory parameter determines whether only top-level categories (those with no parent) will be included in the results.

Response Details

For a successful response, XML is returned with a BusinessCategoryLinkList root element containing an entries element for each matched category. The entries element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Business Category record's internal ID

recordLink

string

URI to the BusinessCategoryService Retrieve record service for this category

code

string

Code business key to the Business Category record

entityDescription

string

Category's name

path

string

Category's full path (including parent levels - separated by '/')

Error Messages

Element Message Meaning

specificationType

<###> is not a valid Specification Type

Specification type not found

pageSize

Error Code: INVALIDPAGESIZE

Page Size must be between 1 and 100

offset

Error Code: INVALIDOFFSET

Offset must be a positive integer

code

Error Code: INVALIDBUSINESSCATEGORY

Invalid Business Category

parentCode

Error Code: INVALIDBUSINESSCATEGORY

Invalid Business Category

specificationType

Error Code: INVALIDSPECIFICATIONTYPE

Invalid SpecificationType

topLevelCategory

Error Code: INVALIDBOOLEAN

Invalid topLevelCategory value

Permitted values (not case-sensitive) are: true; yes; 1; false; no; 0

Retrieve Record by ID

Description

Retrieves a single Business Category record's details using the record's unique ID. Use this function to retrieve the full details of an individual category.

Endpoint address: /services/rest/businessCategory/{id} HTTP method: GET

Request Details

There are no request parameters, but the URL contains the {id} parameter that determines the record to retrieve.

Example URL

…/services/rest/businessCategory/105

Response Details

For a successful response, an HTTP 301 message is returned, which is automatically acted upon to retrieve XML consisting of a BusinessCategoryFullDTO root element containing the individual attributes of the requested Business Category record. If an ID is not specified, a list of all categories is returned (per the List of Values function).

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 1 - Framework for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

id

HTTP 404 Not found

Invalid {id} - not numeric

id

Invalid record id

Invalid {id} - not found

Check Record Modification Timestamp

Description

Retrieves the last modification date and time of a Business Category record. Use this function to determine when a category's details were last updated.

Endpoint address: /services/rest/businessCategory/{id} HTTP method: HEAD

Request Details

There are no request parameters, but the URL contains the {id} parameter that determines the record to retrieve.

Example URL

…/services/rest/businessCategory/105

Response Details

If successful, an HTTP 200 response is sent containing the Last-Modified header showing the date and time of the last update of the requested Business Category record. For example:

HTTP/1.1 200 OK
Date: Wed, 13 Jul 2016 07:52:14 GMT
Last-Modified: Fri, 08 Jul 2016 06:44:46 GMT
Content-Type: application/xml
Content-Length: 0

Error Messages

Element Message Meaning

id

HTTP 417 Expectation Failed

Invalid {id} - not found

id

HTTP 404 Not found

Invalid {id} - not numeric

Create Record

Description

Creates a new Business Category record. Use this function to create a new category in Supplier Evaluation based on data sourced from the external system.

Dependencies: If a lower-level category, the parent Business Category must be present in the application and its record ID obtained. For more information, see Dependencies.

Endpoint address: /services/rest/businessCategory HTTP method: POST

Request Details

The body of the request contains a BusinessCategoryFullDTO to specify the details of the category to create. Compared to retrieving a user (which uses the same BusinessCategoryFullDTO type), this request is much shorter. Only the attributes that are to be populated on the created Business Category record need to be included. As a minimum, this must include the fields shown in the following table:

Business Category Mandatory Fields

Field Name Element Name

Code

code

Description

description

Parent Code

parentCode

Parent or Child level

topLevelCategory

Deleted Record

deleted (Set to false)

Path

path (The category's full path descriptions, concatenated and separated by /)

Note:

If creating a top level category, topLevelCategory must be set to true; if creating a lower level category, topLevelCategory must be set to false, and parentCode becomes mandatory (the parent category's code).

Example Request XML

<ns0:businessCategoryFullDTO xmlns:ns0="http://www.micros.com/creations/core/domain/dto/v1p0/full" xmlns:ns1="http://www.micros.com/creations/core/domain/dto/v1p0/simple">
   <ns0:code>X1</ns0:code>
   <ns0:localeData>
      <ns0:description>Category X - Level 1</ns0:description>
      <ns0:path>Category X - Level 1</ns0:path>
   </ns0:localeData>
   <ns0:topLevelCategory>true</ns0:topLevelCategory>
   <ns0:deleted>false</ns0:deleted>
</ns0:businessCategoryFullDTO>

Set the deleted attribute to false to ensure the record can be seen in the UI. If omitted or set to true, it will exist, but will not be visible.

The following example adds a second level category to the above top-level parent category:

<ns0:businessCategoryFullDTO xmlns:ns0="http://www.micros.com/creations/core/domain/dto/v1p0/full" xmlns:ns1="http://www.micros.com/creations/core/domain/dto/v1p0/simple">
   <ns0:code>X2</ns0:code>
   <ns0:localeData>
      <ns0:description>Category X - Level 2</ns0:description>
      <ns0:path>Category X - Level 1 / Category X - Level 2</ns0:path>
   </ns0:localeData>
   <ns0:parentCode>X1</ns0:parentCode>
   <ns0:topLevelCategory>false</ns0:topLevelCategory>
   <ns0:deleted>false</ns0:deleted>
</ns0:businessCategoryFullDTO>

The value of the code element must be unique.

The description and path elements are locale-dependent, so are contained within a localeData element, with a locale element supported language code, for example:

<ns0:localeData>
        <ns0:description>Cheese</ns0:description>
        <ns0:locale>en_GB</ns0:locale>
</ns0:localeData>

<ns0:localeData>
       <ns0:description>Fromage</ns0:description>
       <ns0:locale>fr</ns0:locale>
</ns0:localeData>

The hierarchy of category levels is maintained through the parent code, linking a category to its immediate parent. All levels except the top level must therefore have a valid parent code specified.

The number of levels in the hierarchy is defined in the Supplier Evaluation Admin area.

Categories may be assigned to specific product specifications, or available for use by all; if specified, the specification type must be match those assigned to its parent categories.

Where the record is linked to another record, such as the Locale in this case, the business key must be provided (not the description) in order to form the link between the records. In general, the business key will be the code attribute of the linked record.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 1 - Framework for details of their mapping to the fields within the Supplier Evaluation UI.

Response Details

For a successful response, an HTTP 200 response is sent with a body containing a BusinessCategoryLink root element. The root element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Newly created Business Category record's internal ID

recordLink

string

URI to the newly created Business Category record, for use in a GET request

code

string

Code ID business key to the newly created Business Category record

entityDescription

string

Category's description

Error Responses

If the supplied data does not result in a valid Business Category (such as a missing mandatory field), an HTTP 417 response is sent with an XML body message stating the validation errors. The request should not be reattempted with the same content.

Error Messages

Element Message Meaning

code

Code {0} has already been used

Codes must be unique

parent

The Parent Code cannot be blank when the Top Level Category flag is false

A parent code must be specified unless the category is a top level category

topLevelCategory

The Top Level Category flag cannot be true when the Parent Code has a value

A category cannot be a top level category and have a parent

description

Description must be provided

Descriptions are mandatory

code

The parent Business Category with code {0} cannot be found

The parent category must exist

parent

A new Business Category cannot be added to the Business Category with the code{0} because it will fall outside of the Business Category Hierarchy

Categories can only be added within the bounds of the Business Category Hierarchy as defined in Supplier Evaluation's Admin/System Control/Business Category Configuration

specificationType

{0} is not a valid Specification Type(s)

The specification type or types must be valid

specificationType

The Specification Types must be a subset of the parent Business Category's Specification Types: {0}

This message is issued when no specification types are specified on a child, but there are specification types assigned to the parent

It lists the specification types selected on the parent

specificationType

The Business Category Specification Types {0} are not a subset of the parent Business Category Specification Types {1}

This message is issued when the category's specification types have not all be selected on the parent

The child's specification types are listed in {0} and the parent's specification types are listed in {1}

Update Record

Description

Updates an existing Business Category record. Use this function to update a category's details in Supplier Evaluation based on data sourced from the external system, or to move a category to appear beneath a different parent category.

Endpoint address: /services/rest/businessCategory/{id} HTTP method: PUT

Request Details

The body of the request contains a BusinessCategoryUpdateDTO to specify the updates to the Business Category record.

The request content is similar to that for creating a category, but does not include the child categories link. If children are to be managed, then a separate call is required for each child. As a minimum, the values specified as mandatory for the Create Record function (see above) must be included.

After the call, the Business Category record is updated to match the request.

Note:

When updating records, all values must be included. If a value or element is omitted from the request, the field contents will be cleared on the Business Category record.

The id element is used to locate the category to update.

The hierarchy of category levels is maintained through the parent code, linking a category to its immediate parent. All levels except the top level must therefore have a valid parent code specified.

The number of levels in the hierarchy is defined in the Supplier Evaluation Admin area.

Categories may be assigned to specific product specifications, or available for use by all; if specified, the specification type must be match those assigned to its parent categories.

Categories may be moved to the same level within another part of the hierarchy. When a category is moved, its children are automatically moved.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 1 - Framework for details of their mapping to the fields within the Supplier Evaluation UI.

The body of the request contains a BusinessCategoryUpdateDTO element to specify how the category should appear after the update.

Response Details

If successful, an HTTP 200 response is sent with a body containing a BusinessCategoryLink element. The BusinessCategoryLink element consists of the returned elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Business Category record's internal ID

recordLink

string

URI to the Business Category record, for use in a GET request

code

string

Code ID business key to the Business Category record

entityDescription

string

Category's description

path

string

Category's full path (including parent levels - separated by '/')

Error Responses

If the supplied data does not result in a valid Business Category (such as a missing mandatory field), an HTTP 417 response is sent with an ErrorMessage/Message XML body message stating the validation errors. The request should not be reattempted with the same content.

Error Messages

Element Message Meaning

recordId

Invalid record id

The ID used to call the PUT process does not relate to an existing record

parent

The Parent Code cannot be blank when the Top Level Category flag is false

A parent code must be specified unless the category is a top level category

topLevelCategory

The Top Level Category flag cannot be true when the Parent Code has a value

A category cannot be a top level category and have a parent

code

The parent Business Category with code {0} cannot be found

The parent category must exist

code

A new Business Category cannot be added to the Business Category with the code{0} because it will fall outside of the Business Category Hierarchy

Categories can only be added within the bounds of the Business Category Hierarchy as defined in Supplier Evaluation's Admin/System Control/Business Category Configuration

parent

Business Category cannot be moved from a parent at level {0} to a parent at level {1}

Categories can only be moved between parent categories at the same level in the hierarchy

specificationType

{0} is not a valid Specification Type(s)

The specification type(s) must be valid

specificationType

The Specification Types must be a subset of the parent Business Category's Specification Types: {0}

This message is issued when no specification types are specified on a child but there are specification types assigned to the parent

It lists the specification types selected on the parent

specificationType

The Business Category Specification Types {0} are not a subset of the parent Business Category Specification Types {1}

This message is issued when the category's specification types have not all be selected on the parent

The child's specification types are listed in {0} and the parent's specification types are listed in {1}

Delete Record

Description

Deletes an existing Business Category record, along with any associated child categories. Use this function to remove a single category or a category and all its lower level categories.

Endpoint address: /services/rest/businessCategory/{id} HTTP method: DELETE

Request Details

There are no request parameters, but the URL contains the {id} parameter that determines the record to delete.

Response Details

If the Business Category is deleted successfully, an HTTP 200 response is sent.

Error Responses

If a Business Category cannot be deleted due to it being referenced by another record (or a child of the category being referenced by another record), an HTTP 417 response is sent with an ErrorMessage/Message XML body containing the message: "Could not delete: with a URI link to the category."

Error Messages

Element Message Meaning

id

HTTP 417 Could not delete: {URI}

Category is referenced by another record

id

HTTP 404 Not found

Invalid {id} - not numeric

id

Invalid record id for deletion

Invalid {id} - not found

AuditRestService

This section describes the API for managing audit and visits. The following functions are available:

List of Values (Audit)

Description

Retrieves a list of Audits or Visits in a paged list. Use this function to locate Audit or Visit record IDs prior to a retrieve or update operation. Parameters are available to apply specific selection criteria for filtering the returned records.

Endpoint address: /services/rest/audit HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/ Optional Value Type Multiple Value Separator (~) Supported? Wildcard Search Supported? Example
offset Optional int No No 60
pageSize Optional int No No 30
modifiedSince Optional string No No 2015-05-19 13:30:39
modifiedUntil Optional string No No 2015-05-19 13:30:39
status Optional string Yes No Scheduled~In Progress
softDelete Optional string No No true

Example URL

…/services/rest/audit/?offset=2&pageSize=20

Response Details

For a successful response, XML is returned with an AuditVisitLinkList root element containing an entries element for each matched audit or visit. The entries element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Audit/Visit record's internal ID

recordLink

string

URI to the AuditRestService Retrieve record service for this audit/visit

code

string

Audit/Visit's code business key

dueDate

string

Audit/Visit's due date

siteCode

string

Audit/Visit's site code

supplierCode

string

Audit/Visit's supplier code

templateCode

string

Audit/Visit's template code

Error Messages

Element Message Meaning

pageSize

Error Code: INVALIDPAGESIZE

Page Size must be between 1 and 100

Retrieve Record by ID (Audit)

Description

Retrieves a single Audit or Visit record's details using the record's internal unique ID (which is not visible in the UI). Use this function to retrieve the full details of an individual audit or visit.

Endpoint address: /services/rest/audit/{id} HTTP method: GET

Request Details

The URL contains the {id} parameter that determines the record to retrieve.

URI Parameters

Parameter Name Mandatory/Optional Value Type Multiple Value Separator (~) Supported? Example

locale

Optional

string

Yes

en_GB~fr

Locale country code.

If used, fields that have language translations have a localeData element returned for the specified locales if data is present.

Example URL

…/services/rest/audit/105

Response Details

For a successful response, an HTTP 301 message is returned, which is automatically acted upon to retrieve XML consisting of an AuditFullDTO root element containing the individual attributes of the requested Audit or Visit record. If an ID is not specified, a list of all audits/visits is returned (per the List of Values function).

File Structure:

The main elements of the auditFullDTO root element:

  • auditTemplateSnapshot and Template - the settings from the associated template.

  • nonConformances - If the audit/visit has any non conformances/issues raised against it, they appear within a nonConformances element - a separate element for each.

  • supplier and site - details of the supplier and site that the audit/visit is related to.

  • udfData - the contents of any user-defined custom fields associated to the Audit/Visit record. nonConformances may also contain udfData elements, if the Non Conformance record has user-defined custom fields configured.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

id

HTTP 404 Not Found

Invalid {id} - not numeric

id

HTTP 417 IllegalStateException: Cannot find the Audit to return with id:<###>

Invalid {id} - not found

Retrieve Record by Business Key (Audit)

Description

Retrieves a single Audit or Visit record's details using its business key (code). Use this function to retrieve the full details of an individual audit or visit using its key code.

Endpoint address: /services/rest/audit/byKey/{code} HTTP method: GET

Request Details

There are no request parameters, but the URL contains the {code} parameter that determines the record to retrieve.

Example URL

…/services/rest/audit/byKey/110

Response Details

If successful, an HTTP 301 redirect response is sent containing a header Location with the URI of the document requested.

The returned URI represents the call to be made to the Retrieve Record by ID function (with the id substituted with the relevant value), which will return an AuditFullDTO Element Message containing the individual attributes of the requested Audit or Visit record.

Note:

If your method of calling the API is configured to automatically follow HTTP 301 redirects, the call may automatically return a AuditFullDTO root element containing the individual attributes of the requested Audit or Visit record.

File Structure:

The main elements of the auditFullDTO root element:

  • auditTemplateSnapshot and Template - the settings from the associated template.

  • nonConformances - If the audit/visit has any non conformances/issues raised against it, they appear within a nonConformances element - a separate element for each.

  • supplier and site - details of the supplier and site that the audit/visit is related to.

  • udfData - the contents of any user-defined custom fields associated to the Audit/Visit record. nonConformances may also contain udfData elements, if the Non Conformance record has user-defined custom fields configured.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

code

HTTP 404 Not Found

Invalid {code} - blank or not found

code

HTTP 404 Not Found

Invalid {code} - not found

Check Record Modification Timestamp (Audit)

Description

Retrieves the last modification date and time of an Audit or Visit record. Use this function to determine when the audit or visit was last updated.

Endpoint address: /services/rest/audit/{id} HTTP method: HEAD

Request Details

There are no request parameters, but the URL contains the {id} parameter that determines the record to retrieve.

Example URL

…/services/rest/audit/105

Response

If successful, an HTTP 200 response is sent containing the Last-Modified header to show the last modification date and time of the last update of the requested Audit or Visit record.

HTTP/1.1 200 OK
Date: Wed, 13 Jul 2016 07:52:14 GMT
Last-Modified: Fri, 08 Jul 2016 06:44:46 GMT
Content-Type: application/xml
Content-Length: 0

Error Messages

Element Message Meaning

id

HTTP 417 Expectation Failed

Invalid {id} - not found

id

HTTP 404 Not Found

Invalid {id} - not numeric

Create Record (Audit)

Description

Creates a new Audit or Visit record. Use this function to create a new audit or visit in Supplier Evaluation based on data sourced from the external system.

Dependencies: The Supplier and Site must be present in the application and its record ID obtained. If assigning a Business Category, the ID of the Business Category record must be present in the application and its record ID obtained. If assigning a Technologist or People Present, the users must be present in the application and the record IDs of the User record obtained. If non conformances/issues are to be included, and they are associated to a specific user of the application, the record IDs of the User record must be obtained. An audit/visit must be associated to an audit/visit template. For more information, see Dependencies.

Endpoint address: /services/rest/audit HTTP method: POST

Request Details

The body of the request contains an AuditFullDTO element to specify the detail of the audit or visit to create, which is based on the AuditFullDTO element returned when retrieving an audit/visit. As a minimum, the fields shown in the following table must be populated.

Audit/Visit Mandatory Fields

Field Name Element Name

Audit/Visit Template

template / id (or code)

auditTemplateSnapshot

Audit/Visit Code

code

Lead Technologist

leadTechnicalManager / code

Supplier

supplier / id

Site

site / id

Due Date

dueDate

Record Type

recordType

Status

status / id

From Date

fromDate

To Date

toDate

People Present

peoplePresent / name

Deleted Record

deleted (Set to false)

Note:

If the status is Scheduled, fromDate, toDate, and peoplePresent are not mandatory.

To ensure a valid unique business key code is automatically assigned to the record being created, a value of zero must be passed in the <code> element of the XML when submitting the POST request.

People Present Table:

This table is used to identify the people present during the audit or visit. The options for completing the table depend on the settings in the audit/visit's template:

  • The table must contain at least one entry (whether an audit or a visit).

  • If a visit or an internal audit, the entry should be a user of the system who has a Technologist role and is set as an approved auditor. The template may have been set to just allow specific auditors.

  • If a third-party audit, the entry should be a Certification Body. The template may have been set to just allow specific auditors.

  • Rows of free text may be added to the table.

File Structure:

The main elements of the AuditFullDTO root element are shown in the following table:

Summary of AuditFullDTO Elements

Element Name Description

announced

costChargedToSupplier

auditTemplateSnapshot

Values from the audit/visit template, required to control the record's behavior when it is progressed within Supplier Evaluation.

code

The audit/visit's business key.

dueDate

fromDate

toDate

leadTechnical Manager

recordType

Values that may be mandatory for the audit/visit to be created.

nonConformances

Container for the non conformance data - a separate element for each non conformance/issue.

supplier

ID of the supplier that the audit/visit is associated to.

site

ID of the site that the audit/visit is associated to.

status

The audit/visit's status.

template

ID of the audit/visit template that the audit/visit is associated to.

Example Request XML

This example shows the minimum requirement to be able to create an In Progress audit or visit.

<ns0:auditFullDTO xmlns:ns0="http://www.micros.com/creations/core/domain/dto/v1p0/full" xmlns:ns1="http://www.micros.com/creations/core/domain/dto/v1p0/simple">
   <ns0:announced>true</ns0:announced>
   <ns0:costChargedToSupplier>false</ns0:costChargedToSupplier>
   <ns0:auditTemplateSnapshot>
       <ns0:allowWorkingOffline>false</ns0:allowWorkingOffline>
       <ns0:allowableScoreOptions>
           <ns1:code>AMBER</ns1:code>
       </ns0:allowableScoreOptions>
       <ns0:allowableScoreOptions>
           <ns1:code>GREEN</ns1:code>
       </ns0:allowableScoreOptions>
       <ns0:auditType>INTERNAL</ns0:auditType>
       <ns0:auditVisibility>OPTIONAL</ns0:auditVisibility>
       <ns0:autoSchedule>false</ns0:autoSchedule>
       <ns0:buyerInformationRequired>true</ns0:buyerInformationRequired>
       <ns0:categoriesRequired>2</ns0:categoriesRequired>
       <ns0:categoryRequired>false</ns0:categoryRequired>
       <ns0:certificationBodiesSelectable>ALL</ns0:certificationBodiesSelectable>
       <ns0:closureDeadline>56</ns0:closureDeadline>
       <ns0:closureDeadlineNoOfDays>0</ns0:closureDeadlineNoOfDays>
           <ns0:commentsNotVisibleToOrganisationRequired>true
       </ns0:commentsNotVisibleToOrganisationRequired>
       <ns0:costChargedToSupplier>false</ns0:costChargedToSupplier>
       <ns0:defaultFrequency>12</ns0:defaultFrequency>
       <ns0:defaultIssueCompletion>28</ns0:defaultIssueCompletion>
       <ns0:extendedDeadline>56</ns0:extendedDeadline>
       <ns0:extendedDeadlineNoOfDays>0</ns0:extendedDeadlineNoOfDays>
       <ns0:internalAuditorsSelectable>ALL</ns0:internalAuditorsSelectable>
       <ns0:isActive>true</ns0:isActive>
       <ns0:localeData>
           <ns0:name>Checklist Audit</ns0:name>
           <ns0:id>49</ns0:id>
       </ns0:localeData>
       <ns0:mayExternalManagersEditConfig>MAY_NOT_EDIT
       </ns0:mayExternalManagersEditConfig>
       <ns0:nonConformanceCreationMethod>VIA_CHECKLISTS
       </ns0:nonConformanceCreationMethod>
       <ns0:organisationType>SITE</ns0:organisationType>
       <ns0:recordType>AUDIT</ns0:recordType>
       <ns0:scoreAudit>true</ns0:scoreAudit>
       <ns0:scoreRequired>true</ns0:scoreRequired>
       <ns0:stampOrgWithLastAuditDate>true</ns0:stampOrgWithLastAuditDate>
       <ns0:supplierGenerated>false</ns0:supplierGenerated>
       <ns0:useAuditVisitStandards>false</ns0:useAuditVisitStandards>
       <ns0:id>6</ns0:id>
  </ns0:auditTemplateSnapshot>
  <ns0:dueDate>2017-04-27</ns0:dueDate>
  <ns0:fromDate>2017-04-27</ns0:fromDate>
  <ns0:leadTechnicalManager>
      <ns1:code>PROD-TECH</ns1:code>
      <ns1:disabled>false</ns1:disabled>
      <ns1:externalAuthenticationUser>false</ns1:externalAuthenticationUser>
      <ns1:timeZone>Europe/London</ns1:timeZone>
      <ns1:userType>RETAILER</ns1:userType>
      <ns1:id>12</ns1:id>
  </ns0:leadTechnicalManager>
  <ns0:nonConformances>
      <ns0:description>&lt;p>Test&lt;/p></ns0:description>
      <ns0:reference>AR01</ns0:reference>
      <ns0:status>
          <ns1:status>OPEN</ns1:status>
      </ns0:status>
      <ns0:type>
          <ns1:code>MAJOR</ns1:code>
      </ns0:type>
      <ns0:code>AR01-11</ns0:code>
   </ns0:nonConformances>
   <ns0:recordType>AUDIT</ns0:recordType>
   <ns0:site>
       <ns1:id>27</ns1:id>
   </ns0:site>
   <ns0:status>
       <ns1:status>IN PROGRESS</ns1:status>
   </ns0:status>
   <ns0:supplier>
       <ns1:id>21</ns1:id>
   </ns0:supplier>
   <ns0:template>
       <ns1:id>8</ns1:id>
   </ns0:template>
   <ns0:toDate>2017-04-27</ns0:toDate>
   <ns0:code>AR1</ns0:code>
   <ns0:deleted>false</ns0:deleted>
</ns0:auditFullDTO>

Set the deleted attribute to false to ensure the record can be seen in the UI. If omitted or set to true, it will exist, but will not be visible.

Where the record is linked to another record, such as the Template, the business key or ID must be provided (not the description) in order to form the link between the records. In general, the business key will be the code attribute of the linked record. The supplier and site elements can contain just the ID of the respective record links.

A unique code for the audit/visit must be assigned.

Templates:

The audit/visit is linked to its template using the template and auditTemplateSnapshot elements. The template element can contain just the code or ID of the associated Template record.

The auditTemplateSnapshot element must be completed to provide the parameters that control the audit/visits' behavior as it progresses through its Supplier Evaluation workflow. If scoring is used, the allowable options can be specified using the code or ID of the glossary record; if none are specified, all options will be available when the user selects the score.

Non Conformances:

If the audit/visit is to be created with non conformances/issues already raised against it, they can be added within a nonConformances element - a separate element for each. A unique code must be assigned to each. The status can be set using its code or ID.

For further information about the process for creating audit, non conformances and checklists, see Dependencies.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Response Details

If successful, an HTTP 200 response is sent with a body containing a AuditVisitLink root element. The root element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Newly created Audit/Visit record's internal ID

recordLink

string

URI to the newly created Audit/Visit record, for use in a GET request

code

string

Audit/Visit's code business key

dueDate

string

Audit/Visit's due date

siteCode

string

Audit/Visit's site code

supplierCode

string

Audit/Visit's supplier code

templateCode

string

Audit/Visit's template code

Error Responses

If the supplied data does not result in a valid Audit or Visit (such as a missing mandatory field), an HTTP 417 response is sent with an ErrorMessage/Message XML body message stating the validation errors. The request should not be reattempted with the same content.

Error Messages

Element Message Meaning

peoplePresent

WARNING: class com.micros.creations.core.domain.Audit.peoplePresent - There must be at least one entry in the People Present table

People Present not provided

recordType

IllegalArgumentException: No enum constant com.micros.creations.core.type.AuditRecordType. <###>

Record Type not found

supplier/id

code

site/id

code

supplierId

supplierCode

HTTP 417 IllegalStateException: Cannot locate keyword for class com.micros.creations.core.domain.Site using id: <###>, code:<###>, supplierCode:<###> and supplierId:<###>

Site Id not found

Site Code not found

Supplier Id not found

Supplier Code not found

template

EntityNotFoundException: Unable to find com.micros.creations.core.domain.AuditTemplate with id <###>

Template not found

fromDate

ERROR: class com.micros.creations.core.domain.Audit.fromDate - The condition is invalid

From Date not provided

code

ERROR: class com.micros.creations.core.domain.Audit.code - The condition is invalid

Audit/Visit code not provided

code

ERROR: class com.micros.creations.core.domain.Audit.code - Another object exists with this value

Audit/Visit code already exists

Update Record (Audit)

Description

Updates an existing Audit or Visit record. Use this function to update an audit or visit's details in Supplier Evaluation based on data sourced from the external system.

Endpoint address: /services/rest/audit/{id} HTTP method: PUT

Request Details

The body of the request contains an AuditFullDTO element to specify the updates to the Audit or Visit record, which is based on the AuditFullDTO type returned when retrieving an audit/visit.

Note:

The request content is similar to that for creating an audit or visit.

As a minimum, the values specified as mandatory for the Create Record function (see above) must be included. However, when updating records, all values must be included.

If a value or element is omitted from the request, the field contents will be cleared on the Audit/Visit record.

If the audit/visit has any non conformances/issues raised against it, they appear within a nonConformances element - a separate element for each. The non conformances/issues can be updated or created when updating the audit/visit. If creating a new Non Conformance record, assign a unique code and omit the id element.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Response Details

If successful, an HTTP 200 response is sent with a body containing an AuditVisitLink element. The AuditVisitLink element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Audit/Visit record's internal ID

recordLink

string

URI to the Audit/Visit record, for use in a GET request

code

string

Audit/Visit's code business key

dueDate

string

Audit/Visit's due date

siteCode

string

Audit/Visit's site code

supplierCode

string

Audit/Visit's supplier code

templateCode

string

Audit/Visit's template code

Error Responses

If the supplied data does not result in a valid Audit or Visit (such as a missing mandatory field), an HTTP 417 response is sent with an ErrorMessage/Message XML body message stating the validation errors. The request should not be reattempted with the same content.

List of Values (Checklist)

Description

Retrieves a list of Checklists in a paged list. Use this function to locate Checklist record IDs prior to a retrieve or update operation. Parameters are available to apply specific selection criteria for filtering the returned records.

Endpoint address: /services/rest/audit/{auditId}/checklist HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/ Optional Value Type Multiple Value Separator (~) Supported? Wildcard Search Supported? Example
auditId Optional long No No 105
offset Optional int No No 60
pageSize Optional int No No 30

Example URL

…/services/rest/audit/105/checklist/?offset=2&pageSize=20

Response Details

For a successful response, XML is returned with an AuditChecklistLinkList root element containing an entries element for each matched audit or visit. The entries element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Checklist record's internal ID

recordLink

string

URI to the AuditRestService Retrieve record service for this checklist

parentId

string

The parent Audit/Visit's internal ID

auditCode

string

The parent Audit/Visit's code business key

globalId

string

Checklist's code business key

Error Messages

In the event that an error occurs, an HTTP 500 response is sent.

Retrieve Record by ID (Checklist)

Description

Retrieves a single Checklist record's details using the record's internal unique ID (which is not visible in the UI) and its parent audit/visit's internal unique Id. Use this function to retrieve the full details of an individual audit or visit.

Endpoint address: /services/rest/audit/{auditId}/checklist/{id} HTTP method: GET

Request Details

The URL contains the {auditId} parameter that identifies the parent Audit/Visit record, and the {id} parameter that determines the record to retrieve.

URI Parameters

Parameter Name Mandatory/Optional Value Type Multiple Value Separator (~) Supported? Example

locale

Optional

string

Yes

en_GB~fr

Locale country code.

If used, fields that have language translations have a localeData element returned for the specified locales if data is present.

Example URL

…/services/rest/audit/105/checklist/7

Response Details

For a successful response, an HTTP 301 message is returned, which is automatically acted upon to retrieve XML consisting of an auditChecklistFullDTO root element containing the individual attributes of the requested Checklist record. If a Checklist ID is not specified, a list of all the audit/visit's checklists is returned (as per the List of Values function).

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

auditId

HTTP 404 Not found

Invalid {auditId} - not numeric

auditId

HTTP 417 IllegalStateException: Cannot find the Audit to return with id:<###>

Invalid {auditId} - not found

id

HTTP 404 Not Found

Invalid {id} - not numeric

id

HTTP 417 IllegalStateException: Cannot find the Audit to return with id:<###>

Invalid {id} - not found

Retrieve Record by Business Key (Checklist)

Description

Retrieves a single Checklist record's details using its business key (code) and its parent audit/visit's code. Use this function to retrieve the full details of an individual checklist using its key code.

Endpoint address: /services/rest/audit/byKey/{auditCode}/checklist/{checklistCode} HTTP method: GET

Request Details

There are no request parameters, but the URL contains the {auditCode} parameter that identifies the parent Audit/Visit record, and the {checklistCode} parameter that determines the record to retrieve.

Example URL

…/services/rest/audit/byKey/110/checklist/7374be1e-2a6c-11e7-8fda-0021f60dd918

Response Details

If successful, an HTTP 301 redirect response is sent containing a header Location with the URI of the document requested.

The returned URI represents the call to be made to the Retrieve Record by ID function (with the id substituted with the relevant value), which will return an auditChecklistFullDTO root element containing the individual attributes of the requested Checklist record.

Note:

If your method of calling the API is configured to automatically follow HTTP 301 redirects, the call may automatically return a auditChecklistFullDTO root element containing the individual attributes of the requested Checklist record.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

auditCode

HTTP 404 Not Found

Invalid {auditCode} - blank or not found

checklistCode

HTTP 404 Not Found

Invalid {checklistCode} - blank or not found

Create Record (Checklist)

Description

Creates a new Checklist record. Use this function to create a new checklist in Supplier Evaluation based on data sourced from the external system.

Dependencies: To create an audit with a checklist, the parent Audit record must be created using the Create Record (Audit/Visit) function, before creating the associated Checklist records.

Therefore, when creating the checklist, the parent Audit/Visit record must be present in the application and its record ID obtained. A checklist's questions and the permitted answers are determined by the checklist template that has been assigned to the audit/visit's template. The IDs of the Checklist Template record must also be provided when creating a template. For more information, see Dependencies.

Endpoint address: /services/rest/audit{auditId}/checklist HTTP method: POST

Request Details

The body of the request contains an auditChecklistFullDTO element to specify the detail of the checklist to create, which is based on the auditChecklistFullDTO element returned when retrieving a checklist. As a minimum, the fields shown in the following table must be populated.

Checklist Mandatory Fields

Field Name Element Name

Audit/Visit Id

audit / id See note 1.

Audit/Visit Code

audit /code See note 1.

Checklist Template

localeData / id

Checklist Comments Allowed

commentsAllowed

Questionnaire Questions

questionnaire / questionnaireQuestion / questionDetails

Question Answers

questionnaire / questionnaireQuestion / questionnaireAnswer

questionnaire / questionnaireQuestion / quesAvailAnsFull

Deleted Record

deleted (Set to false)

Notes:

  1. Either code or ID may be specified to identify the audit/visit.

File Structure:

The following diagram shows the structure of the auditChecklistFullDTO request file structure:

Figure 4-3 RESTful Checklist Request

This figure shows a checklist request.

Summary of AuditChecklistFullDTO Elements

Element Name Description

audit

Identifies the parent audit record by code or id.

commentsAllowed

A value from the checklist template, required to control the record's behavior when it is progressed within Supplier Evaluation.

localeName

Identifies the checklist template by name and id.

questionnaire

Groups the questions and their answers.

questionnaireQuestion

Groups the checklist questions and their answers - repeated for each question in the checklist.

reference is the question reference.

questionDetails

Individual questions.

question is the question text.

answerComment is the answer's comments (if configured).

answerFieldType is code of answer type (MULTI_SELECTION, TEXT, or SINGLE_SELECTION).

commentAllowed is whether comments are allowed.

questionnaireAnswer

Groups the answer details.

questionnaireAvailableAnswer

Answers for the individual questions.

code is the question's unique key.

commentMandatory is whether comments are mandatory or not.

generateNonConformance is whether an answer will generate an issue.

quesAvailAnsFull

The available answers - repeated for each answer.

code is the question's unique key.

commentMandatory is whether comments are mandatory or not.

id and keywordTypeEnum are the keys to the Issues glossary.

Process for Creating Checklist Audits

The general process for creating checklist audits:

  1. Create the Audit/Visit. While it is possible to create a checklist audit using the Create Audit function, it is recommended that they be created within the Supplier Evaluation application.

    A method of creating a new audit:

    1. Retrieve an existing audit using a GET function.

    2. Omit the id and statusChangeHistory elements from the retrieved file.

    3. Omit localData elements from status and allowableAuditStandards.

    4. Assign a new unique code.

    5. Link to the Supplier, Site, and Audit Template records using the relevant IDs.

    6. Change other content to reflect the new audit.

    7. Submit using the POST function.

    8. If non conformances are to be created at the time of creating the audit/visit, include them as nonConformances elements.

      Note:

      The API does not automatically create a non conformance based on the answer of a checklist question. Non conformances must be assigned when either creating or updating the Audit/Visit record.

  2. Retrieve the code or ID of the newly created Audit, and its template detail using a GET function.

  3. Create the checklist using the POST function (repeat for each checklist):

    • Identify the parent audit/visit by setting the code or id within audit element.

    • Can retrieve an existing checklist using a GET function, in which case the id and questionnaireQuestionAvailableAnswer elements must be omitted. Also omit any id elements within the questionnaire element, except those that relate to the auditNonConformance element.

Example Request XML

This example shows the minimum requirement to be able to create an audit checklist. This example contains three questions, each with the available answers of Yes, No, or Not Applicable.

Figure 4-4 Checklist Questions

This figure shows checklist questions.
<ns0:auditChecklistFullDTO xmlns:ns1="http://www.micros.com/creations/core/domain/dto/v1p0/simple" xmlns:ns0="http://www.micros.com/creations/core/domain/dto/v1p0/full">
    <ns0:audit>
        <ns1:code>AUD09</ns1:code>
        <ns1:id>132</ns1:id>
    </ns0:audit>
    <ns0:commentsAllowed>false</ns0:commentsAllowed>
    <ns0:localeData>
        <ns0:name>
            <![CDATA[ API Test Template ]]>
        </ns0:name>
        <ns0:id>563</ns0:id>
    </ns0:localeData>
    <ns0:questionnaire>
        <ns0:questionnaireQuestion>
            <ns0:localeData>
                <ns0:reference>
                    <![CDATA[Ref1]]>
                </ns0:reference>
            </ns0:localeData>
            <ns0:questionDetails>
                <ns0:answerComment>
                    <![CDATA[Yes comment]]>
                </ns0:answerComment>
                <ns0:answerFieldType>SINGLE_SELECTION</ns0:answerFieldType>
                <ns0:commentAllowed>true</ns0:commentAllowed>
                <ns0:localeData>
                    <ns0:question>
                        <![CDATA[Question 1]]>
                    </ns0:question>
                </ns0:localeData>
            </ns0:questionDetails>
            <ns0:questionnaireAnswer>
                <ns0:questionnaireAvailableAnswer>
                    <ns1:code>QQAA7236</ns1:code>
                    <ns1:commentMandatory>false</ns1:commentMandatory>
                    <ns1:generateNonConformance>false
                    </ns1:generateNonConformance>
                    <ns1:localeData>
                        <ns0:answer>Yes</ns0:answer>
                    </ns1:localeData>
                </ns0:questionnaireAvailableAnswer>
                <ns0:questionnaireQuestion>
                    <ns1:localeData>
                        <ns0:reference>
                            <![CDATA[Ref1]]>
                        </ns0:reference>
                    </ns1:localeData>
                </ns0:questionnaireQuestion>
            </ns0:questionnaireAnswer>
            <ns0:quesAvailAnsFull>
                <ns0:code>QQAA7236</ns0:code>
                <ns0:commentMandatory>false</ns0:commentMandatory>
                <ns0:generateNonConformance>false</ns0:generateNonConformance>
                <ns0:localeData>
                    <ns0:answer>Yes</ns0:answer>
                </ns0:localeData>
            </ns0:quesAvailAnsFull>
            <ns0:quesAvailAnsFull>
                <ns0:code>QQAA7237</ns0:code>
                <ns0:commentMandatory>true</ns0:commentMandatory>
                <ns0:generateNonConformance>true</ns0:generateNonConformance>
                <ns0:localeData>
                    <ns0:answer>No</ns0:answer>
                </ns0:localeData>
            </ns0:quesAvailAnsFull>
            <ns0:quesAvailAnsFull>
                <ns0:code>QQAA7238</ns0:code>
                <ns0:commentMandatory>false</ns0:commentMandatory>
                <ns0:generateNonConformance>false</ns0:generateNonConformance>
                <ns0:localeData>
                    <ns0:answer>Not Applicable</ns0:answer>
                </ns0:localeData>
            </ns0:quesAvailAnsFull>
        </ns0:questionnaireQuestion>
        <ns0:questionnaireQuestion>
            <ns0:localeData>
                <ns0:reference>
                    <![CDATA[Ref2]]>
                </ns0:reference>
            </ns0:localeData>
            <ns0:questionDetails>
                <ns0:answerComment>
                    <![CDATA[No comment]]>
                </ns0:answerComment>
                <ns0:answerFieldType>SINGLE_SELECTION</ns0:answerFieldType>
                <ns0:commentAllowed>true</ns0:commentAllowed>
                <ns0:localeData>
                    <ns0:question>
                        <![CDATA[Question 2]]>
                    </ns0:question>
                </ns0:localeData>
            </ns0:questionDetails>
            <ns0:questionnaireAnswer>
                <ns0:questionnaireAvailableAnswer>
                    <ns1:code>QQAA7240</ns1:code>
                    <ns1:commentMandatory>true</ns1:commentMandatory>
                    <ns1:generateNonConformance>true</ns1:generateNonConformance>
                <ns1:localeData>
                    <ns0:answer>No</ns0:answer>
                </ns1:localeData>
            </ns0:questionnaireAvailableAnswer>
            <ns0:questionnaireQuestion>
                <ns1:localeData>
                    <ns0:reference>
                        <![CDATA[Ref2]]>
                    </ns0:reference>
                </ns1:localeData>
            </ns0:questionnaireQuestion>
        </ns0:questionnaireAnswer>
        <ns0:quesAvailAnsFull>
            <ns0:code>QQAA7239</ns0:code>
            <ns0:commentMandatory>false</ns0:commentMandatory>
            <ns0:generateNonConformance>false</ns0:generateNonConformance>
            <ns0:localeData>
                <ns0:answer>Yes</ns0:answer>
            </ns0:localeData>
        </ns0:quesAvailAnsFull>
        <ns0:quesAvailAnsFull>
            <ns0:code>QQAA7240</ns0:code>
            <ns0:commentMandatory>true</ns0:commentMandatory>
            <ns0:generateNonConformance>true</ns0:generateNonConformance>
            <ns0:localeData>
                <ns0:answer>No</ns0:answer>
            </ns0:localeData>
        </ns0:quesAvailAnsFull>
        <ns0:quesAvailAnsFull>
            <ns0:code>QQAA7241</ns0:code>
            <ns0:commentMandatory>false</ns0:commentMandatory>
            <ns0:generateNonConformance>false</ns0:generateNonConformance>
            <ns0:localeData>
                <ns0:answer>Not Applicable</ns0:answer>
            </ns0:localeData>
        </ns0:quesAvailAnsFull>
    </ns0:questionnaireQuestion>
    <ns0:questionnaireQuestion>
        <ns0:localeData>
            <ns0:reference>
                <![CDATA[Ref3]]>
            </ns0:reference>
        </ns0:localeData>
        <ns0:questionDetails>
            <ns0:answerComment>
                <![CDATA[N/A comment]]>
            </ns0:answerComment>
            <ns0:answerFieldType>SINGLE_SELECTION</ns0:answerFieldType>
            <ns0:commentAllowed>true</ns0:commentAllowed>
            <ns0:localeData>
                <ns0:question>
                    <![CDATA[Question 3]]>
                </ns0:question>
            </ns0:localeData>
        </ns0:questionDetails>
        <ns0:questionnaireAnswer>
            <ns0:questionnaireAvailableAnswer>
                <ns1:code>QQAA7244</ns1:code>
                <ns1:commentMandatory>false</ns1:commentMandatory>
                <ns1:generateNonConformance>false</ns1:generateNonConformance>
                <ns1:localeData>
                    <ns0:answer>Not Applicable</ns0:answer>
                </ns1:localeData>
             </ns0:questionnaireAvailableAnswer>
             <ns0:questionnaireQuestion>
                 <ns1:localeData>
                     <ns0:reference>
                         <![CDATA[Ref3]]>
                     </ns0:reference>
                 </ns1:localeData>
             </ns0:questionnaireQuestion>
         </ns0:questionnaireAnswer>
         <ns0:quesAvailAnsFull>
             <ns0:code>QQAA7242</ns0:code>
             <ns0:commentMandatory>false</ns0:commentMandatory>
             <ns0:generateNonConformance>false</ns0:generateNonConformance>
             <ns0:localeData>
                 <ns0:answer>Yes</ns0:answer>
             </ns0:localeData>
         </ns0:quesAvailAnsFull>
         <ns0:quesAvailAnsFull>
             <ns0:code>QQAA7243</ns0:code>
             <ns0:commentMandatory>true</ns0:commentMandatory>
             <ns0:generateNonConformance>true</ns0:generateNonConformance>
             <ns0:localeData>
                 <ns0:answer>No</ns0:answer>
             </ns0:localeData>
         </ns0:quesAvailAnsFull>
         <ns0:quesAvailAnsFull>
             <ns0:code>QQAA7244</ns0:code>
             <ns0:commentMandatory>false</ns0:commentMandatory>
             <ns0:generateNonConformance>false</ns0:generateNonConformance>
             <ns0:localeData>
                 <ns0:answer>Not Applicable</ns0:answer>
             </ns0:localeData>
         </ns0:quesAvailAnsFull>
     </ns0:questionnaireQuestion>
</ns0:questionnaire>
<ns0:globalId>7470e250-36cc-4dea-a0f1-eb6040185865</ns0:globalId>
<ns0:deleted>false</ns0:deleted>
</ns0:auditChecklistFullDTO>

Set the deleted attribute to false to ensure the record can be seen in the UI. If omitted or set to true, it will exist, but will not be visible.

For further information about the process for creating audit, non conformances, and checklists, see Dependencies.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Response Details

If successful, an HTTP 200 response is sent with a body containing an AuditChecklistLink root element. The root element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Checklist record's internal ID

recordLink

string

URI to the newly created Checklist record, for use in a GET request

parentId

long

The parent Audit/Visit's internal ID

auditCode

string

The parent Audit/Visit's code business key

globalId

string

Checklist's code business key

Error Responses

If the supplied data does not result in a valid Checklist (such as a missing mandatory field), an HTTP 417 response is sent with an ErrorMessage/Message XML body message stating the validation errors. The request should not be reattempted with the same content.

Error Messages

Element Message Meaning

audit / id

audit / code

HTTP 417 IllegalStateException: The checklists audit cannot be located

Audit/Visit id/code not found

id

HTTP 417 IllegalStateException: Cannot find matching relation to update on <###> looking for <###>

Invalid link to related record

Update Record (Checklist)

Description

Updates an existing Checklist record. Use this function to update a checklist's details in Supplier Evaluation based on data sourced from the external system.

Endpoint address: /services/rest/audit/{auditId}/checklist/{id} HTTP method: PUT

Request Details

The body of the request contains an auditChecklistFullDTO element to specify the updates to the Audit or Visit record, which is based on the auditChecklistFullDTO type which is returned when retrieving an audit/visit.

Note:

The request content is similar to that for creating a checklist.

As a minimum, the values specified as mandatory for the Create Record function (see above) must be included. However, when updating records, all values must be included.

If a value or element is omitted from the request, the field contents will be cleared on the Checklist record.

The link to the parent Audit/Visit record is defined by the code or ID within the audit element.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Response Details

If successful, an HTTP 200 response is sent with a body containing an auditChecklistLink element. The auditChecklistLink element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Checklist record's internal ID

recordLink

string

URI to the Checklist record, for use in a GET request

parentId

long

The parent Audit/Visit's internal ID

auditCode

string

The parent Audit/Visit's code business key

globalId

string

Checklist's code business key

Error Messages

If the supplied data does not result in a valid Audit or Visit (such as a missing mandatory field), an HTTP 417 response is sent with an ErrorMessage/Message XML body message stating the validation errors. The request should not be reattempted with the same content.

Delete Record (Checklist)

Deletes an existing Checklist record. Use this function to delete a checklist that has been created in error from the external system

Endpoint address: /services/rest/audit/{auditId}/checklist/{id} HTTP method: DELETE

Request Details

There are no request parameters, but the URL contains the {auditId} parameter that identifies the parent Audit/Visit record, and the {id} parameter that determines the record to delete.

Note:

It is not possible to manually delete checklists from an audit/visit within the application; this delete function has been provided solely for the deletion of checklists that have been created in error by the API.

To delete a checklist, the external system must be granted access to the AUDIT_CHECKLIST_DELETE endpoint.

Example URL

…/services/rest/audit/105/checklist/7

Response Details

If successful, an HTTP 200 response is sent.

Error Messages

Element Message Meaning

auditId

HTTP 404 Not Found

Invalid {auditId} - not numeric

auditId

HTTP 417 IllegalStateException: Cannot find the Audit to return with id:<###>

Invalid {auditId} - not found

id

HTTP 404 Not Found

Invalid {id} - not numeric

id

HTTP 417 IllegalStateException: Cannot find the Audit Checklist to return with id:<###>

Invalid {id} - not found

DataPrivacyService

This section describes the API for executing Data Privacy requests. The following functions are available:

Although minimal personal data is held in Supplier Evaluation, it does include the names and contact details of retailer/portal owner, supplier, and third-party users. The Data Privacy API provides a means for the retailer/portal owner to:

  1. Request details of personal data relating to an individual be held within the system.

  2. Request that the personal data relating to the individual be removed from the system.

For additional detail on using the Data Privacy API, including examples, see Appendix: Using the Data Privacy API.

Right to Access

Description

Retrieves a set of personal data that relates to the name of an individual. Use this function to perform Right to Access requests for the following scenarios:

  • An employee of the retailer/portal owner requests an electronic copy of their personal data that is held within the system.

  • An employee of one of the retailer/portal owner's suppliers requests an electronic copy of their personal data that is held within the system.

  • An employee of the retailer/portal owner's partner organizations requests an electronic copy of their personal data that is held within the system.

The API's access function allows the name of the individual to be passed, with an XML message being returned containing any personal data found for that name. The XML message is a structured text format, which is both machine and human readable.

Figure 4-5 Right to Access Process

img/right_to_access.png

The steps for completing a Right to Access request are as follows (for further details, see Appendix: Using the Data Privacy API):

  1. Submit a POST call, passing the name of the individual.

    A batch job is submitted within Supplier Evaluation to search the system for personal data for the presence of the name (for which records and fields are searched, see Appendix: Using the Data Privacy API). On completion, a Data Privacy record containing the retrieved personal data is created within Supplier Evaluation.

    A link to the Data Privacy record is returned as the response to the POST call.

  2. On receipt of the response to the POST call, submit a GET call, passing the returned URI link.

    Note:

    If the GET call is submitted before the batch job has finished compiling the personal data, just a header will be returned, and the GET call should be retried.

    A message containing the personal data is returned. The XML data is structured within a dataprivRequestDTO root element (for details of the message structure, see Appendix: Using the Data Privacy API).

    Just the personal data fields and values to identify the record are returned, not the full record contents.

    Addresses may contain multiple localeData elements for the language translation of countries.

    XML elements will only be present if they contain data.

  3. Assess whether the returned data relates to the individual who made the request, editing and/or reformatting it if necessary, before passing it to the requestor.

Endpoint address: /services/rest/datapriv/access HTTP methods: POST, GET

Request Details

For the POST method, a name parameter is passed in the payload.

For the GET method, an id parameter is passed as a URI parameter.

URI Parameters

Example URL (POST method): …/services/rest/access/

Example URL (GET method): …/services/rest/access/?id=16

Response Details

For a successful response to the POST method, a link to the Data Privacy record is returned.

For a successful response to the GET method, XML is returned with a dataprivRequestDTO root element containing an element for each record where the personal data has been found.

Error Responses

In the event that an error occurs, an HTTP 500 response is sent.

Right to be Forgotten

Description

Erases a set of personal data that relates to an individual. Use this function to perform Right to be Forgotten requests for the following scenarios:

  • An employee of the retailer/portal owner requests their personal data be erased from the system.

  • An employee of one of the retailer/portal owner's suppliers requests their personal data be erased from the system.

  • An employee of a partner organizations requests their personal data be erased from the system.

  • The retailer/portal owner initiates the purging of an inactive user's personal data from the system.

An erase function allows the XML message returned from a Right to Access request to be used to erase the data.

Figure 4-6 Right to be Forgotten Process

img/right_to_be_forgotten.png

The steps for completing a Right to be Forgotten request are as follows:

  1. The Right to Access service must be used to retrieve the personal data for the individual. For details, see Right to Access

    .

  2. View, and if necessary, edit the XML returned from the Right to Access request.

    As there may be any number of users with the same name, it is necessary to decide which data represents the individual who made the request, removing any that is not relevant (for further information on editing the XML message, see Appendix: Using the Data Privacy API).

  3. Optionally submit a POST call to the verify function, passing the login id of the individual (obtained from the XML message returned in Step 2).

    This step is used to check whether the erasure of data for the individual will be permitted, before actually submitting the request. The erase will not be permitted if the individual is responsible for the completion of a supplier site's Assessment.

    XML is returned with a dataprivVerifyDTO root element containing a status and a message element. If the call is successful the message will contain Success, otherwise it will contain Failure and the reason for the failure will be present in the message element.

  4. Submit a POST call to the erase function, passing the XML retrieved from the Right to Access request (with any edits having been applied).

    A batch job is submitted to validate the request, verify that the erasure is permitted (that is, the individual is not responsible for the completion of an Assessment), and obtain locks on the records to be updated.

  5. If the validation fails, or a lock cannot be obtained, the process is terminated and an XML is returned with a dataprivErasureDTO root element containing a message element that contains the reason for the failure, and the status element set to Failure.

    If no exceptions are encountered, a Data Privacy record containing the personal data to erase is created and a link to the record is returned as the response to the POST call.

  6. On receipt of the response to the POST call, submit a GET call to the erase function, using the returned URI link.

    The update processing replaces the data passed in the XML message with 30 characters of randomly-generated text. Email addresses are changed to x@example.com, where x is 15 characters of randomly-generated text*. GPS coordinate numbers and country selections are blanked.

    Some fields have a specific length, in which case the 30 characters of obfuscated text is overridden:

    • Name 50 characters

    • Login 20 characters

    • Address lines 20 characters

    • Post Code 5 characters

    * Email addresses that are stored as free text are fully obfuscated, rather than set to x@example.com.

    Only certain fields are permitted to be erased (for details, see Appendix: Using the Data Privacy API).

    When updating a user account, the account is set to deactivated, and the password is set to expired.

    Note:

    If the GET call is submitted before the batch job has finished compiling the personal data, just a header will be returned, and the GET call should be retried.

    The erasure of data is not reversible.

  7. Optionally submit another Right to Access request to check that the data has been erased as expected.

  8. Inform the requestor of the outcome of their request.

The Right to be Forgotten facility may also be used for purging user accounts that are no longer active.

Endpoint address: /services/rest/datapriv/erase HTTP methods: POST (verify and erase), GET (erase)

Request Details

For the verify POST method, a loginId parameter is passed in the payload.

For the erase POST method, an XML message is passed in the payload.

For the erase GET method, an id parameter is passed as a URI parameter.

URI Parameters

Example URL (verify POST method): …/services/rest/verify/

Example URL (erase POST method): …/services/rest/erase/

Example URL (erase GET method): …/services/rest/erase/?id=32

Response Details

For a successful response to the verify POST method, XML is returned with a dataprivVerifyDTO root element containing a status of Success.

For a successful response to the erase POST method, a link to the Data Privacy record is returned.

For a successful response to the erase GET method, an HTTP 200 response is sent with a dataprivErasureDTO root element containing a status of Success.

Error Responses

For a failure response to the verify method, XML is returned with a dataprivVerifyDTO root element containing a status of Failure, with the reason in the message element.

For a failure response to the erase method, XML is returned with a dataprivErasureDTO root element containing a status of Failure, with the reason in the message element.

Error Messages

Element Message Meaning

user

Only one User can be erased at a time

More than one User was passed in to the erase function. The XML must only relate to a single user.

person

Only one Person can be erased at a time

More than one Person was passed in to the erase function. The XML must only relate to a single person.

id

The User is linked to Person with ID: %id but the Person included has ID: %id

The wrong Person has been included.

%id is the id taken from the XML.

id

The Contacts are linked to Person with ID: %id but the Person included has ID: %id

The wrong Person has been included.

%id is the id taken from the XML.

id

The Contact with ID %id is linked to a different User than the one being erased

The Contacts passed do not match the user being erased. %id is replaced with the id from the XML.

person

All Contacts being erased must be linked to the same Person

Where no User is being erased, all Contacts being erased must be for the same person.

person

Please include Person with ID: %id

If User or Contacts are passed, the matching Person must also be included.

id

Cannot find entity of type: %rec and ID: %id

An id is passed that is not found.

%rec is the internal name of the record, such as ProductRecord. %id is the id taken from the XML.

id

Entity of type: %rec and ID: %id is currently locked, please try again later

One of the records to be erased is currently locked.

%rec is the internal name of the record, such as ProductRecord. %id is the id taken from the XML.

Retry the request until the record becomes available.

id

Entity of type: %rec with id: %id has been edited during the erase process, please verify data

One of the records updated has been edited between up front validation and the processing of that particular record.

%rec is the internal name of the record, such as ProductRecord. %id is the id taken from the XML.

user

The user cannot be erased because they are responsible for the approval of an Assessment

The user is named as being responsible for completing an assessment, so they cannot be erased.

login id

Cannot find User with login ID: %id

No User account found for the passed login id.

%id is the login id.

The erase has failed due to unexpected internal error

Other unexpected condition has occurred.

AttachmentRestService

This section describes the API for retrieving the file attachments from certain records. The following function is available:

Record types that have an attachments element contain a globalId element for each of the record's file attachments. The Retrieve Attachment service can be used to retrieve the actual attachment files by passing globalId as a parameter.

The record types that are capable of returning attachments data are:

  • Users

  • Suppliers

  • Sites

  • Audits

  • Audit Issues (Non Conformances)

  • Scorecards

  • Projects

  • Activities

The following attributes are included in the attachment element of the XML:

  • ID

  • Record Link (global Id for the attachment file)

  • File Name/URL

  • Description

  • Bytes

  • Attached by ID

  • Attached On

The Attachments API is GET (retrieve) only, there is no PUT/POST (update/create) capability.

Retrieving a file returns a fileName element containing the file name, plus the encoded attachment. Retrieving a URL returns a uri element containing the URL.

The following describes the steps for retrieving file attachments:

Figure 4-7 Steps for Retrieving Attachments

This diagram shows the steps for retrieving attachments.

  • Call the List of Values service for the record with appropriate filters to locate the records for which attachments are to be retrieved. Record ids are returned for any records that match search criteria.

  • Call the Retrieve Record by ID service for each record id returned from the List of Values call. The record's full DTO element is returned, containing the record's data, including an attachments element which has a globalId element for each of the record's file attachments.

  • Call the Retrieve Attachment service passing the globalId as a parameter. The attachment file's data is returned as a Base 64 text string. Use a suitable decoder to generate the actual attachment file.

Retrieve Report Attachment

Description

Retrieves an attachment file that has been generated as the output of a report. The file types will be PDF, Excel, RTF, or HTML. When a report is generated, the outputs are stored in the Report Outputs area, grouped within a hierarchical folder structure.

The API provides a means of automatically locating reports for further analysis of the data within an external system. The ID of the attachment to be retrieved is sent to the external system's designated email address.

For additional detail on using the Report Attachment API, see Appendix: Using the Report Attachment API.

Endpoint address: /services/rest/attachment/report/{globalId} HTTP method: GET

Request Details

There are no request parameters, but the URL contains the {globalId} parameter that determines the record to retrieve.

Example URL

…/services/rest/attachment/report/f25eebdd-e7c5-4bb2-b61c-f35171438386

Response Details

For a successful response, XML is returned with a data element which contains the actual attachment as a Base64 encoded text string. The string must then be processed by a Base64 decoder to convert it to the actual report file.

Error Messages

Element Message Meaning

globalId

HTTP 404 Not found

Invalid {globalId} - not numeric

globalId

HTTP 417 IllegalStateException: Cannot find the Attachment to return with id:<###>

Invalid {globalId} - not found

Retrieve Attachment

Description

Retrieves a file that has been attached to a record. The files types will typically be documents or images.

Endpoint address: /services/rest/attachment/attachment/{globalId} HTTP method: GET

Request Details

There are no request parameters, but the URL contains the {globalId} parameter that determines the record to retrieve.

Example URL

…/services/rest/attachment/attachment/RTxy92Ha4lsQE6Bjc-18t1wJ7smbYoCH

Response Details

For a successful response, XML is returned with a data element which contains the actual attachment as a Base64 encoded text string. The string must then be processed by a Base64 decoder to convert it to the actual attachment file.

Error Messages

Element Message Meaning

globalId

HTTP 404 Not found

Invalid {globalId} - not numeric

globalId

HTTP 417 IllegalStateException: Cannot find the Attachment to return with id:<###>

Invalid {globalId} - not found

ScorecardRestService

This section describes the API for managing assessments. The following functions are available:

List of Values

Description

Retrieves a list of assessments in a paged list. Use this function to locate Assessment record IDs prior to a retrieve or update operation. Parameters are available to apply specific selection criteria for filtering the returned records.

Endpoint address: /services/rest/scorecard HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/ Optional Value Type Multiple Value Separator (~) Supported? Wildcard Search Supported? Example
offset Optional int No No 60
pageSize Optional int No No 30
status Optional string Yes Yes IN PROGRESS~COMPLETE
siteStatus Optional string Yes Yes AWAITING REGISTRATION
siteType Optional string Yes Yes PRIMARY
siteCode Optional string Yes Yes A0001-0001
siteName Optional string Yes Yes West Road Site
siteNameBusinessLanguage Optional string Yes Yes West Road Site
supplierCode Optional string Yes Yes A0001
supplierName Optional string Yes Yes ABC Ltd
supplierNameBusinessLanguage Optional string Yes Yes ABC Ltd
businessCategory Optional string Yes Yes POTATOES_LOOSE
templateCode Optional string Yes Yes ETHICAL_ASSESSMENT
dueDate Optional string Yes No 2015-05-19
modifiedSince Optional string No No 2015-05-19 13:30:39
modifiedUntil Optional string No No 2015-05-19 13:30:39

Example URLs

…/services/rest/scorecard/?offset=2&pageSize=20 …/services/rest/scorecard/?status=IN PROGRESS~COMPLETE …/services/rest/scorecard/?businessCategory=POTATOES_LOOSE

Response Details

For a successful response, XML is returned with a ScorecardLinkList root element containing an entries element for each matched assessment. The entries element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Assessment record's internal ID

recordLink

string

URI to the ScorecardRestService Retrieve record service for this assessment

scorecardCode

string

Assessment's code business key

siteCode

string

Assessment's site code

supplierCode

string

Assessment's supplier code

templateCode

string

Assessment's template code

The returned XML also contains a totalRecords element, which states the total number of retrievable records that match the filter parameters.

Error Messages

In the event that an error occurs, an HTTP 500 response is sent.

Retrieve Record by ID

Description

Retrieves a single Assessment record's details using the record's internal unique ID (which is not visible in the UI). Use this function to retrieve the full details of an individual assessment.

Endpoint address: /services/rest/scorecard/{id} HTTP method: GET

Request Details

The URL contains the {id} parameter that determines the record to retrieve.

URI Parameters

Parameter Name Mandatory/Optional Value Type Multiple Value Separator (~) Supported? Example

locale

Optional

string

Yes

en_GB~fr

Locale country code.

If used, fields that have language translations have a localeData element returned for the specified locales if data is present.

Example URL

…/services/rest/scorecard/54

Response Details

For a successful response, an HTTP 301 message is returned, which is automatically acted upon to retrieve XML consisting of a scorecardFullDTO root element containing the individual attributes of the requested Assessment record. If an ID is not specified, a list of all assessments is returned (per the List of Values function).

File Structure

The main elements of the scorecardFullDTO root element:

  • scorecardTemplateSnapshot and Template - the settings from the associated template.

  • scorecardQuestions - the assessment's questions and their answers - a separate element for each.

  • supplier and site - details of the supplier and site that the assessment is related to.

  • udfData - the contents of any user-defined custom fields associated to the Assessment record.

  • attachments - a child element containing the ids of any file attachments the assessment has.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

id

HTTP 404 Not found

Invalid {id} - not numeric

id

HTTP 417 IllegalStateException: Cannot find the Assessment to return with id:<###>

Invalid {id} - not found

Retrieve Record by Business Key

Description

Retrieves a single Assessment record's details using its business key (code). Use this function to retrieve the full details of an individual assessment using its key code.

Endpoint address: /services/rest/scorecard/byKey/{code} HTTP method: GET

Request Details

There are no request parameters, but the URL contains the {code} parameter that determines the record to retrieve.

Example URL

…/services/rest/scorecard/byKey/184

Response Details

For a successful response, an HTTP 301 message is returned, which is automatically acted upon to retrieve XML consisting of a scorecardFullDTO root element containing the individual attributes of the requested Assessment record.

File Structure

The main elements of the scorecardFullDTO root element:

  • scorecardTemplateSnapshot and Template - the settings from the associated template.

  • scorecardQuestions - the assessment's questions and their answers - a separate element for each.

  • supplier and site - details of the supplier and site that the assessment is related to.

  • udfData - the contents of any user-defined custom fields associated to the Assessment record.

  • attachments - a child element containing the ids of any file attachments the assessment has.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 2 - Supplier for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

code

HTTP 404 Not found

Invalid {code} - blank or not found

Check Record Modification Timestamp

Description

Retrieves the last modification date and time of an Assessment record. Use this function to determine when a assessment was last updated.

Endpoint address: /services/rest/scorecard/{id} HTTP method: HEAD

Request Details

There are no request parameters, but the URL contains the {id} parameter that determines the record to retrieve.

Example URL

…/services/rest/scorecard/54

Response Details

If successful, an HTTP 200 response is sent containing the Last-Modified header showing the date and time of the last update of the requested Assessment record. For example:

HTTP/1.1 200 OK
Date: Wed, 13 Jul 2016 07:52:14 GMT
Last-Modified: Fri, 08 Jul 2016 06:44:46 GMT
Content-Type: application/xml
Content-Length: 0

Error Messages

Element Message Meaning

id

HTTP 417 Expectation Failed

Invalid {id} - not found

id

HTTP 404 Not found

Invalid {id} - not numeric

ProjectRestService

This section describes the API for managing processes. The following functions are available:

List of Values

Description

Retrieves a list of processes in a paged list. Use this function to locate Process record IDs prior to a retrieve or update operation. Parameters are available to apply specific selection criteria for filtering the returned records.

Endpoint address: /services/rest/project HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/ Optional Value Type Multiple Value Separator (~) Supported? Wildcard Search Supported? Example
offset Optional int No No 60
pageSize Optional int No No 30
projectStatus Optional string Yes Yes IN PROGRESS~COMPLETED
templateCode Optional string Yes Yes NEW_BAKERY_RANGE
masterProject Optional Boolean No No TRUE
parentProject Optional string Yes Yes NEW_LINE_DEVELOPMENT
projectType Optional string Yes Yes CHANGE OF SUPPLIER
projectName Optional string Yes Yes New Potato Product Launch
projectManager Optional string Yes Yes John Smith
businessCategory Optional string Yes Yes POTATOES_LOOSE
specificationType Optional string Yes Yes FOOD
siteStatus Optional string Yes Yes AWAITING REGISTRATION
siteType Optional string Yes Yes PRIMARY
siteCode Optional string Yes Yes A0001-0001
siteName Optional string Yes Yes West Road Site
siteNameBusinessLanguage Optional string Yes Yes West Road Site
supplierCode Optional string Yes Yes A0001
supplierName Optional string Yes Yes ABC Ltd
supplierNameBusinessLanguage Optional string Yes Yes ABC Ltd
modifiedSince Optional string No No 2015-05-19 13:30:39
modifiedUntil Optional string No No 2015-05-19 13:30:39

Example URLs

…/services/rest/user/?offset=2&pageSize=20 …/services/rest/user/?projectStatus=IN PROGRESS~COMPLETED …/services/rest/user/?templateCode=NEW_LINE_DEVELOPMENT

Response Details

For a successful response, XML is returned with a ProjectLinkList root element containing an entries element for each matched process. The entries element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Process record's internal ID

recordLink

string

URI to the ProjectRestService Retrieve record service for this process

projectId

string

Process's business key

projectName

string

Process's name

parentProjectId

string

Parent process's business key

parentProjectName

string

Parent process's name

The returned XML also contains a totalRecords element, which states the total number of retrievable records that match the filter parameters.

Error Messages

In the event that an error occurs, an HTTP 500 response is sent.

Retrieve Record by ID

Description

Retrieves a single Process record's details using the record's internal unique ID (which is not visible in the UI). Use this function to retrieve the full details of an individual process.

Endpoint address: /services/rest/project/{id} HTTP method: GET

Request Details

The URL contains the {id} parameter that determines the record to retrieve.

URI Parameters

Parameter Name Mandatory/Optional Value Type Multiple Value Separator (~) Supported? Example

locale

Optional

string

Yes

en_GB~fr

Locale country code.

If used, fields that have language translations have a localeData element returned for the specified locales if data is present.

Example URL

…/services/rest/project/20

Response Details

For a successful response, an HTTP 301 message is returned, which is automatically acted upon to retrieve XML consisting of a projectFullDTO root element containing the individual attributes of the requested Process record. If an ID is not specified, a list of all processs is returned (per the List of Values function).

File Structure

The main elements of the projectFullDTO root element:

  • projectTemplateSnapshot and Template - the settings from the associated template.

  • briefs - the associated process briefs; a separate element for each.

  • teams - the users and their roles associated to the process.

  • linkedRecords - the associated linked records; a separate element for each.

  • udfData - the contents of any user-defined custom fields associated to the Process record.

  • attachments - a child element containing the ids of any file attachments the process has.

Processes and their activities can be nested within a hierarchy. In the absence of a function to extract the full hierarchy with a single GET call, to retrieve the hierarchy of a process a number of successive calls is required. The Parent Project field is a Boolean value which will be blank for processes that have no hierarchy, or are at the top level of the hierarchy. Use the id or code of the Parent Project to traverse the levels. Use the Activities endpoints to retrieve the process's activity details. Master processes will not have a parent project id or a process name.

If a process is linked to a record such as an Audit, the linkedRecords element contains a list of the linked records, containing the id and business key of the record (audit code, supplier code, or site code), its type, name and status, and the date it was created.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 3 - Process for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

id

HTTP 404 Not found

Invalid {id} - not numeric

id

HTTP 417 IllegalStateException: Cannot find the Process to return with id:<###>

Invalid {id} - not found

Retrieve Record by Business Key

Description

Retrieves a single Process record's details using its business key (code). Use this function to retrieve the full details of an individual process using its key code.

Endpoint address: /services/rest/project/byKey/{code} HTTP method: GET

Request Details

There are no request parameters, but the URL contains the {code} parameter that determines the record to retrieve.

Example URL

…/services/rest/project/byKey/943

Response Details

For a successful response, an HTTP 301 message is returned, which is automatically acted upon to retrieve XML consisting of a projectFullDTO root element containing the individual attributes of the requested Process record.

File Structure

The main elements of the projectFullDTO root element:

  • projectTemplateSnapshot and Template - the settings from the associated template.

  • teams - the users and their roles associated to the process.

  • briefs - the associated process briefs; a separate element for each.

  • linkedRecords - the associated linked records; a separate element for each.

  • udfData - the contents of any user-defined custom fields associated to the Process record.

  • attachments - a child element containing the ids of any file attachments the process has.

Processes and their activities can be nested within a hierarchy. In the absence of a function to extract the full hierarchy with a single GET call, to retrieve the hierarchy of a process a number of successive calls is required. The Parent Project field is a Boolean value which will be blank for processes that have no hierarchy, or are at the top level of the hierarchy. Use the id or code of the Parent Project to traverse the levels. Use the Activities endpoints to retrieve the process's activity details. Master processes will not have a parent project id or a process name.

If a process is linked to a record such as an Audit, the linkedRecords element contains a list of the linked records, containing the id and business key of the record (audit code, supplier code, or site code), its type, name and status, and the date it was created.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 3 - Process for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

code

HTTP 404 Not found

Invalid {code} - blank or not found

Check Record Modification Timestamp

Description

Retrieves the last modification date and time of a Process record. Use this function to determine when the process was last updated.

Endpoint address: /services/rest/project/{id} HTTP method: HEAD

Request Details

There are no request parameters, but the URL contains the {id} parameter that determines the record to retrieve.

Example URL

…/services/rest/project/20

Response Details

If successful, an HTTP 200 response is sent containing the Last-Modified header showing the date and time of the last update of the requested Processord. For example:

HTTP/1.1 200 OK
Date: Wed, 13 Jul 2016 07:52:14 GMT
Last-Modified: Fri, 08 Jul 2016 06:44:46 GMT
Content-Type: application/xml
Content-Length: 0

Error Messages

Element Message Meaning

id

HTTP 417 Expectation Failed

Invalid {id} - not found

id

HTTP 404 Not found

Invalid {id} - not numeric

ActivityRestService

This section describes the API for managing process activities. The following functions are available:

List of Values

Description

Retrieves a list of activities in a paged list. Use this function to locate Activity record IDs prior to a retrieve or update operation. Parameters are available to apply specific selection criteria for filtering the returned records.

Endpoint address: /services/rest/activity HTTP method: GET

Request Details

Parameters are passed as URI parameters.

URI Parameters

Parameter Name Mandatory/ Optional Value Type Multiple Value Separator (~) Supported? Wildcard Search Supported? Example
offset Optional int No No 60
pageSize Optional int No No 30
recordId Optional string Yes Yes 1
projectId Optional string Yes Yes PR0000007
projectName Optional string Yes Yes New Potato Product Launch
activityName Optional string Yes Yes Artwork
activityCode Optional string Yes Yes 762
activityStatus Optional string Yes Yes STARTED~COMPLETED
activitySubStatus Optional string Yes Yes MESSAGE SENT
activityType Optional string Yes Yes PRODUCT_ARTWORK

templateCode

 Optional string Yes Yes ARTWORK
linkedRecord Optional string Yes No

Note: Options are:

ASSESSMENT

SUPPLIER

SITE

AUDIT

PRODUCT_RECORD

PRODUCT_SPECIFICATION
personResponsibleName Optional string Yes Yes John Smith
proposedStartDate Optional string No No 2015-05-19
proposedEndDate Optional string No No 2015-05-19
actualStartDate Optional string No No 2015-05-19
actualEndDate Optional string No No 2015-05-19

sequenceNumber

 Optional string Yes Yes 1.0
modifiedSince Optional string No No 2015-05-19 13:30:39
modifiedUntil Optional string No No 2015-05-19 13:30:39

Example URLs

…/services/rest/user/?offset=2&pageSize=20 …/services/rest/user/?activityStatus=STARTED~COMPLETED

Response Details

For a successful response, XML is returned with a ProjectActivityLinkList root element containing an entries element for each matched process. The entries element consists of the elements shown in the following table.

Returned Elements

Element Type Description

recordId

long

Process Activity record's internal ID

recordLink

string

URI to the AcitvityRestService Retrieve record service for this activity

activityCode

string

Process Activity's business key

projectRecordId

string

The parent Process's internal ID

projectId

string

The parent Process's business key

The returned XML also contains a totalRecords element, which states the total number of retrievable records that match the filter parameters.

Error Messages

In the event that an error occurs, an HTTP 500 response is sent.

Retrieve Record by ID

Description

Retrieves a single Activity record's details using the record's internal unique ID (which is not visible in the UI). Use this function to retrieve the full details of an individual process activity.

Endpoint address: /services/rest/activity/{id} HTTP method: GET

Request Details

The URL contains the {id} parameter that determines the record to retrieve.

URI Parameters

Parameter Name Mandatory/Optional Value Type Multiple Value Separator (~) Supported? Example

locale

Optional

string

Yes

en_GB~fr

Locale country code.

If used, fields that have language translations have a localeData element returned for the specified locales if data is present.

Example URL

…/services/rest/activity/5

Response Details

For a successful response, an HTTP 301 message is returned, which is automatically acted upon to retrieve XML consisting of a projectActivityFullDTO root element containing the individual attributes of the requested Activity record.

File Structure

The main elements of the projectActivityFullDTO root element:

  • activityTemplateSnapshot and Template - the settings from the associated template.

  • briefs - the associated process briefs; a separate element for each.

  • linkedRecords - the associated linked records; a separate element for each.

  • udfData - the contents of any user-defined custom fields associated to the Activity record.

  • attachments - a child element containing the ids of any file attachments the activity has.

If an activity is linked to a record such as an Audit, the linkedRecords element contains a list of the linked records, containing the id and business key of the record (audit code, supplier code, or site code), its type, name and status, and the date it was created.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 3 - Process for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

id

HTTP 404 Not found

Invalid {id} - not numeric

id

HTTP 417 IllegalStateException: Cannot find the Activity to return with id:<###>

Invalid {id} - not found

Retrieve Record by Business Key

Description

Retrieves a single Activity record's details using its business key (code) and its parent process's code. Use this function to retrieve the full details of an individual activity using its key code.

Endpoint address: /services/rest/activity/byKey/{activityCode} HTTP method: GET

Request Details

There are no request parameters, but the URL contains the {activityCode} parameter that determines the record to retrieve.

Example URL

…/services/rest/activity/byKey/762

Response Details

For a successful response, an HTTP 301 message is returned, which is automatically acted upon to retrieve XML consisting of a projectActivityFullDTO root element containing the individual attributes of the requested Activity record.

File Structure

The main elements of the projectActivityFullDTO root element:

  • activityTemplateSnapshot and Template - the settings from the associated template.

  • briefs - the associated process briefs; a separate element for each.

  • linkedRecords - the associated linked records; a separate element for each.

  • udfData - the contents of any user-defined custom fields associated to the Activity record.

  • attachments - a child element containing the ids of any file attachments the activity has.

If an activity is linked to a record such as an Audit, the linkedRecords element contains a list of the linked records, containing the id and business key of the record (audit code, supplier code, or site code), its type, name and status, and the date it was created.

See the associated WADL for a full list of the attributes, and the Oracle Retail Supplier Evaluation Cloud Service Data Dictionary, Volume 3 - Process for details of their mapping to the fields within the Supplier Evaluation UI.

Error Messages

Element Message Meaning

activityCode

HTTP 404 Not found

Invalid {activityCode} - blank or not found

Check Record Modification Timestamp

Description

Retrieves the last modification date and time of an Activity record. Use this function to determine when the process activity was last updated.

Endpoint address: /services/rest/activity/{id} HTTP method: HEAD

Request Details

There are no request parameters, but the URL contains the {id} parameter that determines the record to retrieve.

Example URL

…/services/rest/activity/5

Response Details

If successful, an HTTP 200 response is sent containing the Last-Modified header showing the date and time of the last update of the requested Activity record. For example:

HTTP/1.1 200 OK
Date: Wed, 13 Jul 2016 07:52:14 GMT
Last-Modified: Fri, 08 Jul 2016 06:44:46 GMT
Content-Type: application/xml
Content-Length: 0

Error Messages

Element Message Meaning

id

HTTP 417 Expectation Failed

Invalid {id} - not found

id

HTTP 404 Not found

Invalid {id} - not numeric