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.
Related Record Links
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. |
Notes:
-
User record ID link: UserRestService - Retrieve Record by ID
-
User business key link: UserRestService - Retrieve Record by Business Key
-
Site record ID link: SiteRestService - Retrieve Record by ID
-
Site business key link: SiteRestService - Retrieve Record by Business Key
-
Supplier record ID link: SupplierRestService - Retrieve Record by ID
-
Supplier business key link: SupplierRestService - Retrieve Record by Business Key
-
Contact record ID link: ContactRestService - Retrieve Record by ID
-
Business Category record ID link: BusinessCategoryService - Retrieve Record
-
Audit/Visit Record ID link: AuditRestService - Retrieve Record by ID (Audit)