APIs Available in Supplier Evaluation

3 APIs Available in Supplier Evaluation

The APIs deployed in a particular implementation of Supplier Evaluation can be found at /services: https://<hostname>/<context>/services.

Individual Services

The following table lists the individual services available in Supplier Evaluation, indicating at which version each was introduced and, where appropriate, at which version it was deprecated.

Supplier Evaluation API Services

Service Name and Functions	Description	Type
UserRestService
List of Values	Retrieves a list of retailer or supplier users in a paged list.	REST
Retrieve Record by ID	Retrieves a single user's details. There are no request parameters, but the URL contains the id parameter that determines the record to retrieve.	REST
Retrieve Record by Business Key	Retrieves a single user's details. There are no request parameters, but the URL contains the login id parameter that determines the record to retrieve.	REST
Check Record Modification Timestamp	Retrieves the last modification time for a user. There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
Create Record	Creates a new retailer or supplier user.	REST
Update Record	Updates an existing retailer or supplier user.	REST
SupplierRestService
List of Values	Retrieves a list of suppliers in a paged list.	REST
Retrieve Record by ID	Retrieves a single supplier's details. There are no request parameters, but the URL contains the id parameter that determines the record to retrieve.	REST
Retrieve Record by Business Key	Retrieves a single supplier's details. There are no request parameters, but the URL contains the key code parameter that determines the record to retrieve.	REST
Check Record Modification Timestamp	Retrieves the last modification time for a supplier. There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
Create Record	Creates a new supplier.	REST
Update Record	Updates an existing supplier .	REST
SiteRestService
List of Values	Retrieves a list of sites in a paged list.	REST
Retrieve Record by ID	Retrieves a single site's details. There are no request parameters, but the URL contains the id parameter that determines the record to retrieve.	REST
Retrieve Record by Business Key	Retrieves a single site's details. There are no request parameters, but the URL contains the supplier and site code parameters that determine the record to retrieve.	REST
Check Record Modification Timestamp	Retrieves the last modification time for a site. There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
Create Record	Creates a new site.	REST
Update Record	Updates an existing site.	REST
ContactRestService
List of Values	Retrieves a list of contacts in a paged list.	REST
Retrieve Record by ID	Retrieves a single contact's details. There are no request parameters, but the URL contains the id parameter that determines the record to retrieve.	REST
Retrieve Supplier Contact Record by Business Key	Retrieves a single supplier contact's details. There are no request parameters, but the URL contains the supplier code, name, and email address parameters that determine the record to retrieve.	REST
Retrieve Site Contact Record by Business Key	Retrieves a single site contact's details. There are no request parameters, but the URL contains the supplier and site codes, name, and email address parameters that determine the record to retrieve.	REST
Check Record Modification Timestamp	Retrieves the last modification time for a contact. There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
BusinessCategoryService
List of Values	Retrieves a list of Business Categories in a paged list.	REST
Retrieve Record	Retrieves a single Business Category (a path of all levels). There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
Check Record Modification Timestamp	Retrieves the last modification time for a Business Category. There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
Create Record	Creates a new Business Category.	REST
Update Record	Updates an existing Business Category.	REST
Delete Record	Deletes an existing Business Category.	REST
AuditRestService
List of Values (Audit)	Retrieves a list of Audits or Visits in a paged list.	REST
Retrieve Record by ID (Audit)	Retrieves a single Audit or Visit (and its Non Conformances/Issues). There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
Retrieve Record by Business Key (Audit)	Retrieves a single Audit or Visit (and its Non Conformances/Issues). There are no request parameters, but the URL contains the key code parameter that determines the record to retrieve.	REST
Check Record Modification Timestamp (Audit)	Retrieves the last modification time for an Audit or Visit. There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
Create Record (Audit)	Creates a new Audit or Visit.	REST
Update Record (Audit)	Updates an existing Audit or Visit.	REST
List of Values (Checklist)	Retrieves a list of Checklists in a paged list.	REST
Retrieve Record by ID (Checklist)	Retrieves a single Checklist. There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
Retrieve Record by Business Key (Checklist)	Retrieves a single Checklist. There are no request parameters, but the URL contains the key code parameter that determines the record to retrieve.	REST
Create Record (Checklist)	Creates a new Checklist.	REST
Update Record (Checklist)	Updates an existing Checklist.	REST
Delete Record (Checklist)	Deletes an existing Checklist.	REST
TaskRestService
List of Values	Retrieves a list of current tasks for the user in the given language.	REST
UrgentAssignmentsRestService
Number of Urgent Items	Retrieves the number of urgent assignments pending for a given user.	REST
ArtworkRestService
Started Activities	Retrieves a list of Project Activities that are flagged as Artwork activities, and their status has changed to Started within the specified date range.	REST
Update Record	Updates the sub-status of existing Artwork Project Activities.	REST
DataPrivacyService
Right to Access	Retrieves personal data from the system relating to the name of an individual.	REST
Right to be Forgotten	Erases personal data from the system for an individual (subject to conditions).	REST
AttachmentRestService
Retrieve Report Attachment	Retrieves attachment files that have been generated by the system as report outputs.	REST
Retrieve Attachment	Retrieves files that have been attached to records.	REST
ScorecardRestService
List of Values	Retrieves a list of Assessments in a paged list.	REST
Retrieve Record by ID	Retrieves a single Assessment. There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
Retrieve Record by Business Key	Retrieves a single Assessment. There are no request parameters, but the URL contains the key code parameter that determines the record to retrieve.	REST
Check Record Modification Timestamp	Retrieves the last modification time for a Assessment. There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
ProjectRestService
List of Values	Retrieves a list of Processes in a paged list.	REST
Retrieve Record by ID	Retrieves a single Process. There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
Retrieve Record by Business Key	Retrieves a single Process. There are no request parameters, but the URL contains the key code parameter that determines the record to retrieve.	REST
Check Record Modification Timestamp	Retrieves the last modification time for a Process. There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
ActivityRestService
List of Values	Retrieves a list of Process Activities in a paged list.	REST
Retrieve Record by ID	Retrieves a single Process Activity. There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST
Retrieve Record by Business Key	Retrieves a single Process Activity. There are no request parameters, but the URL contains the key code parameter that determines the record to retrieve.	REST
Check Record Modification Timestamp	Retrieves the last modification time for a Process Activity. There are no request parameters, but the URL contains the record id parameter that determines the record to retrieve.	REST

Services Grouped by Area

The following sections summarize the service features available by area of Supplier Evaluation functionality.

User and Supplier APIs

The following service features are applicable to the functionality available for user and supplier APIs:

Allows Supplier, Site, Contact, and User records to be created, updated, and extracted.

Does not allow deletion of records.

Does not import or export file attachments.

Does not include Assessments, Audits & Visits, or Alerts.

A system log of service transactions is kept (not reportable).

Audits API

The following service features are applicable to the functionality available for the audits API:

Allows Audit and Visit records to be created, updated, and extracted.

Includes the associated Issues/Non Conformances and Checklists.

Does not allow deletion of records.

Does not import or export file attachments.

A system log of service transactions is kept (not reportable).

Artwork Project Activities

The following service features are applicable to the functionality available for the Artwork Project Activities API:

Enables external Artwork systems to update the sub-status of specific Process Activities that relate to Artwork. The external system is not enabled to complete the activity in Supplier Evaluation; this must be done manually.

Activity templates in the Process module of Supplier Evaluation have an option to integrate that activity with an Artwork system.

Process Activities in Supplier Evaluation, which have been set to integrate with Artwork and which have a status of Started, are available to the external system.

The start and end dates of the Activity are not sent to the Artwork system. The Artwork process is usually well defined and it is usual for a project to be set up in the Artwork system at this point, using the Artwork system's own templates and based on the date that the message is received.

Data Privacy API

The following service features are applicable to the functionality available for the Data Privacy API:

Right to Access requests, to retrieve personal data relating to the name of an individual.

Right to be Forgotten requests, to erase personal data for an individual (subject to conditions).

Certain due diligence approval data is not permitted to be erased.

Data is erased by being overwritten with randomly-generated text.

The erasure of data is not recorded in Change History logs.

Dependencies

Following is the typical sequence of records to be created in order to create all of the above services:

Figure 3-1 Dependencies

The following table indicates the dependencies of each type of record that can be created using the APIs, that is, what configuration or other records must be in place for the creation to succeed:

Record Creation Dependencies

Record Type	Configuration	Other Record Types	Comments
User	Company (mandatory) Languages (mandatory) User Roles (mandatory) Authority Profiles Time Zones Users (Managers and Delegates) Areas	Supplier (if a supplier user)	When creating a user, it is associated to either the retailer or a supplier. If it is a supplier user, the ID of the Supplier record must be provided. The notification email sent to a new user is not generated when creating a user through the API.
Supplier	Billing Codes (mandatory) Business Units (mandatory) Supplier Types (mandatory) Countries Supplier Top Grades Currencies Invoicing Systems Supplier Statuses Areas	NA	When creating a Supplier, omit the Site and Supplier Contact elements, and omit the Billing Details ID. Create Sites, Contacts, AND Users after creating the Supplier. The initial user account is not automatically created when creating a supplier through the API.
Site	Technologists (mandatory) Business Categories (mandatory) Site Types (mandatory) Business Units Currencies Invoicing Systems Countries Audit Reasons Reference Types Reference Statuses Site Top Grades Site Statuses Risk LevelsOther Production Details	Supplier User (Technologist)	When creating a Site, the ID of the Supplier record must be provided. Omit the Assessments and Audit elements, and omit the Billing Details ID and Reference ID. If assigning a Business Category, the ID of the Business Category record must be provided; if assigning a Technologist, the IDs of the User record must be provided. Create Contacts after creating the Site.
Contact	Contact Roles (mandatory)	User Supplier Site (if a Site contact)	When creating a Contact, the IDs of the associated User and Person records must be provided. The Person record holds an individual's personal contact details; the Contact record holds the individual's contact details in relation to that role (which may be different per role); the User record represents the individual's user account. A contact is associated to a supplier and/or a site; the IDs of the Supplier and Site records must be provided as appropriate. Omit the Site element if not a site-level contact.
Business Category	Business Categories (parent levels) Specification Types	NA	When creating a Business Category, if the category is a lower-level category, the ID of its parent Business Category record must be provided.
Audit/Visit	Audit/Visit Template (mandatory) Audit/Visit Status (mandatory) Technologist (mandatory) People Present (mandatory) Supplier Contacts Business Categories Non Conformance: Assigned to Completed by Approved by	Supplier Site User	An Audit or Visit is linked to a supplier/site; the IDs of the Supplier and Site records must be provided. If assigning a Business Category, the ID of the Business Category record must be provided; if assigning a Technologist or People Present, the IDs of the User record must be provided. Non Conformances may include links to User records for the users who the issue is assigned to, was completed by, or is approved by. If the person is not a user of the application, a corresponding text field can be used to record the name. Also, see notes below.
Checklists	Audit/Visit (mandatory) Checklist Question (mandatory)	Audit/Visit Checklist Template	A Checklist is linked to an Audit/Visit, the IDs of the Audit or Visit record must be provided. The Checklist's questionnaire questions and available answers are derived from the Checklist Templates assigned to the Audit/Visit, the IDs of the Template records must be provided.

Notes on the Creation and Maintenance of Audits/Visits and Checklists

The following diagram shows the main links between Audits/Visits, their Checklists, and other entities:

Figure 3-2 Links Between Audits/Visits and Other Entities
For the creation of an Audit/Visit and its Checklists, in addition to providing the links to the associated Audit/Visit Template and Checklist Template records, certain values from the templates must also be included in the payload of the Audit/Visit Create and Update functions.
It is recommended that the creation of Audits/Visits and Checklist be managed within the Supplier Evaluation application. Once created, records can be taken into the external system where the audit is performed, prior to importing back into Supplier Evaluation.

This approach ensures the necessary template fields will have been obtained with the initial Retrieve Record function.

The following diagram shows the stages of a typical scenario:

Figure 3-3 Stages of a Typical Scenario
If it is necessary to create audits or visits from scratch in the external system, the recommended approach would be to create a set of gold standard audits/visits in Supplier Evaluation, which are assigned to a dummy supplier and site.

To create a new audit or visit, the process would be to retrieve the appropriate gold standard audit/visit through the GET function, amend the retuned XML data to reflect the audit/visit to be created, and then submit the creation of the new audit/visit (plus any non conformances and checklists) using the POST function.
If a checklist audit is to be created using the Create Audit service, the Audit/Visit record must first be created using the Create Audit function, followed by the creation of each of its Checklist records.

Creating an audit through the API which is linked to a checklist template does not automatically create the checklists. They must be individually created using the Create Checklist function.
An audit/visit's non conformances are included as separate elements within the audit/visit data. An audit/visit's non conformances are allocated when creating or updating the audit/visit.

Note:

The API does not automatically create non conformances based on the answers of checklist questions.

Linking to Related Records

Links to associated records are included in the XML as an id element, which holds the record ID of the related record. In some cases, a code element also holds the related record's business key.

For example, the XML returned from the SiteRestService API will contain a supplier element, which itself contains an id element and a code element. The value in the id element can be used by the SupplierRestService Retrieve Record by ID function to retrieve the full details of the Supplier record. Alternatively, the value in the code element can be used by the SupplierRestService Retrieve Record by Business Key function to retrieve the Supplier record.

The id element is also used in the XML to hold the record ID of a value that is held in a glossary such as a recipe ingredient or a country.

The following table shows where an API provides links to other records, and the id or code elements used to locate those records. The list of notes below the table indicates the service to use to retrieve the related record.

API	Links to Records
Supplier	Contact: contactDetail/id (Contact record ID link). See note 7. Contact (User): person/id (User record ID link). See note 1. Site: site/id (Site record ID link). See note 3. Site: site/code site (Site business key link). See note 4.
Site	Supplier: supplier/id (Supplier record ID link). See note 5. Supplier: supplier/code (Supplier business key link). See note 6. Business Categories: businessCategories/id (Business Category record ID link). See note 8. Lead Business Category: leadBusinessCategory/id (Business Category record ID link). See note 8. Lead Technologist (User): leadTechnicalManager/id (User record ID link). See note 1. Lead Technologist (User):leadTechnicalManager/code (User business key link). See note 2. Other Technologists (User): otherTMs/id (User record ID link). See note 1. Other Technologists (User): otherTMs/code (User business key link). See note 2. Contact: siteContact/id (Contact record ID link). See note 7.
Contact	Contact (User): person/id (User record ID link). See note 1. Supplier: company/id (Supplier record ID link). See note 5. Supplier: Company/code (Supplier business key link). See note 6. Site: site/id (Site record ID link). See note 3. Site: Site/code (Site business key link). See note 4.
User	Supplier: supplier/id (Supplier record ID link). See note 5. Supplier: Supplier/code (Supplier business key link). See note 6.
Audit/Visit	Supplier: supplier/id (Supplier record ID link). See note 5. Supplier: supplier/code (Supplier business key link). See note 6. Site: site/id (Site record ID link). See note 3. Site: Site/code (Site business key link). See note 4. People Present (User): user/id (User record ID link). See note 1. People Present (User): user/code (User business key link). See note 2. Lead Technologist (User): leadTechnicalManager/id (User record ID link). See note 1. Lead Technologist (User): leadTechnicalManager/code (User business key link). See note 2. Business Categories: businessCategories/id (Business Category record ID link). See note 8. Lead Business Category: leadBusinessCategory/id (Business Category record ID link). See note 8. Non Conformance Assigned To (User): assignedTo/id (User record ID link). See note 1. Non Conformance Completed By (User): completedBy/id (User record ID link). See note 1. Non Conformance Approved By (User): approvedBy/id (User record ID link). See note 1.
Checklist	Audit/Visit: audit/id (Audit/Visit record ID link). See note 9.