E Appendix: LCA Third-Party Integration

Supplier Evaluation can be configured to allow for the integration of Assessments with third parties. This is of use where the retailer or supplier is using a third party such as a Life Cycle Assessment (LCA) partner, to source specialist data, for example sustainability, environmental and ethical analysis information about a supplier or its products.

For a third party to integrate with the Supplier Evaluation system, the retailer portal owner must register them as an Accredited Body and create an External System account, granting them access to the Scorecard API (they may also be granted access to other APIs for the retrieval of supporting Supplier, Site or Product data).

Assessments can be configured to be the type which will be used to capture data from a third party, in which case one or more Accredited Bodies are assigned. When an Assessment of that type is created, one of the permitted Accredited Bodies is selected. That third party is then able to retrieve the Assessment using the Scorecard REST API to supply their data by populating the answers to its questions. They then submit the Assessment’s response answers using the same API.

Once an Assessment is returned it is reviewed, approved and completed. The data provided by the third party then being available for viewing within the Assessment and for use in reports. Summary Attributes may be configured to label responses in a way that they can be shown in the information panels of the associated, Assessment, Site or Product.

The integration may be supplier owned, where the supplier liaises with the third party and has responsibility for the final completion of the Assessment, or retailer owned, where the retailer typically works with the third party without involving the supplier.

When registering a third party as an Accredited Body it is possible to configure a link to the third party’s proprietary system, in which case an option will appear in the top level Accredited Bodies navigation Tasks menu.

Accredited Bodies

The retailer controls which third parties may collaborate by creating an Accredited Body record to register them as a partner, and an External System record to grant them access to the Scorecard API (endpoints for read and update access). The combination of Accredited Body and External System forms the security controls for which third parties may access the API, and to restrict access to specific Assessments.

An Integration Type field on the Assessment Template identifies those where data is to be sourced from third parties. The options of Retailer Owned and Supplier Owned define whether the Assessments are being managed by the retailer or the supplier. Once an Accredited Body is registered, it can be selected within the template as being one of the third parties who may be assigned to Assessments of that type (multiple Accredited Bodies may be assigned to a template).

When an Assessment is created from a template with an Accredited Body assigned, the user selects which single third party will be used to source the data for that Assessment. When the Assign Accredited Body action is used, the status of the Assessment becomes In Progress, and its sub status is set to Pending - meaning it is available for retrieval by the designated third party.

Assessments Integration

The process for third parties to retrieve, respond to, and return Assessments they have been assigned is shown in the following diagrams. The key difference between the two models is: for Supplier Owned, the supplier is notified of the new Assessment and returns the populated Assessment to the retailer, whereas for Retailer Owned, the Assessment is created by the retailer and is assigned directly to the third party, who returns the populated Assessment to the retailer.

Supplier Owned Integration Type

Retailer Owned Integration Type

Sub Status

A Sub Status field on the Assessment is used to control the workflow of those being progressed with a third party:

Third parties retrieve Assessments that have been assigned to them and submit an update to set the sub status to indicate they have been retrieved. Once the questions have been populated with responses that represent the data being provided, a further update is submitted, setting the sub status to indicate they have responded.

Assessment templates have options to set whether the third party and/or the supplier can set an Assessment as being complete, or whether they are submitted for the retailer’s approval.

Using the Scorecard API

The Scorecard API is a RESTful API with XML based interaction and payload, supporting GET and PUT methods for the retrieval and update of Assessments.

Access to the API and its endpoints is controlled by the retailer portal owner, as is the access to the individual Assessments. The retailer portal owner may also grant access to other APIs, such as the Supplier, Site or Product APIs for retrieval of additional supplier or item information. Authentication can be configured utilizing both OAuth 2.0 and Basic Authentication, this must also be configured by the retailer portal owner. The recommendation is to utilize OAuth wherever possible.

The third party’s access to Assessments is restricted to those to which they are the designated Accredited Body, and which are at the appropriate status for retrieval.

Assessments are retrieved with a GET method, and then the responses to the Assessment’s questions can then be returned with a PUT method to update the Assessment. The third party should create a process to periodically call the API to determine if new assessments are available for retrieval. The system does not send notifications when Assessments are assigned to a third party.

When calling the Assessment API, the modifiedSince and modifiedUntil parameters can be used to focus on any assessments that have been created or amended since the previous call. Filtering on the status of the Assessment can be used to exclude any that have previously been completed since the previous call. To facilitate this, the external system will need to record the retailer specific ORSE portal’s URL, authentication method, last called time (for the polling service) and integration frequency/time.

The response to the Get List of Values call will provide a list of links to the Assessments available for retrieval. The individual Assessments are then retrieved by a Retrieve Record by ID call. Once retrieved a call should be made to update the Sub Status of the Assessment, setting it to RETRIEVED to indicate it has been retrieved by the third party – either with the Update Sub Status endpoint or with a full Update message.

The third party can then analyze the questions in the Assessment in the external system and collate the answers before returning their responses with a full Update response. This is achieved by returning the retrieved payload with the responses populated and the Sub Status set to RESPONDED to indicate it is ready for the retailer or supplier to review.

Assessments may be configured to allow the third party to set the Status to COMPLETE, or to set to AWAITING APPROVAL, in which case the supplier or retailer will review for approval before completing it.

The remainder of this section provides more detail on the integration process and the two use cases.

Assessments Integration Process

Consider the following when using the Scorecard API to provide third party data as part of the Assessments integration process.

• Assessments may be Item Assessments for an item/product or Site Assessments for a supplier’s site location. The type is indicated by the Assessment Level field. The same process and endpoints are used for both types.
• As the same Product Number (SKU) may be used by different suppliers (and may change), it is recommended that the Product Code be used to identify a product's Assessments, as it is the unique key of the Product Record.
• Assessment questions have a Question Code, which can be used to map the responses to the questions. Where questions have multiple answer options (checkboxes, radio buttons and picklists), the individual permissible answers each have an Answer Code to be used when populating the answer.
• The Sub Status is initially PENDING, with Status being IN PROGRESS. This is the state when it should be retrieved. Once retrieved the Sub Status should be updated to RETRIEVED. When responses are submitted the Sub Status should be set to RESPONDED, and the Status set to COMPLETE or AWAITING APPROVAL.
  • The Assessment’s template will control whether the third party may progress the Assessment to the Completed status - populating the Completed On (date), Completed By (name of the External System), or whether it must be set to Awaiting Approval for the retailer or supplier to finalize the workflow.
• The third party will liaise offline with the retailer and/or supplier if further action is required.

• The API applies minimal validation; full validation and business logic (calculations, workflow triggers, status changes) when an Assessment record is subsequently edited and progressed within the system. Validation is included in the API to:

  • Prevent the Accredited Body and Integration Type, Accredited Body Can Complete Assessment and Retailer Approval Required values being changed.

  • Control whether the Status can be set to Complete or Awaiting Approval based on the rules for the assessment type:

    • If Accredited Body Can Complete Assessment is Yes, Status can only be set to Complete if Retailer Approval Required is No.
    • If Accredited Body Can Complete Assessment is Yes, Status can only be set to Awaiting Approval if Retailer Approval Required is Yes.
• It is important that when resubmitting an Assessment for update that the full payload remains populated as it was when retrieved - with just the response, status, and any comments data being updated - otherwise the data will be cleared.
• For the scenario where a third party is to periodically update or refresh data as an on-going task, the assessments can be configured by the retailer to automatically schedule the next Assessment on completion.

Supplier Owned Integration Type

For this use case, the retailer requests individual suppliers to progress an Assessment which contains questions for which responses requires third party data. The retailer typically creates the Assessment for the supplier to take responsibility for its completion; alternatively, the supplier may create the Assessment themselves. An Assessment may contain a combination of questions requiring responses to be sourced from the third party and also responses from the supplier. The supplier then submits the Assessment to the retailer if approval is required, otherwise completes it themselves.

Retailer Owned Integration Type

For this use case, the retailer requests a third party to provide data for a product or range of products. The retailer creates the Assessment, which is associated to a supplier (so the supplier will also have access to the Assessment). The third party submits the Assessment to the retailer if approval is required, else completes it themselves.

Enabling Sub Status Endpoints

To enable the endpoints for updating an Assessment’s sub status, add the following Endpoint Access records to the Scorecard Service Access record in the Roles & Permissions section of the Admin area:

Code: SCORECARD

Description: Scorecard RESTful Service

Endpoint Access: SCORECARD_SUB_STATUS and SCORECARD_SUB_STATUS_BY_CODE