Audit and suppliers API

Owned by Søren Riis Mønsted
Last updated: Jul 16, 2024
5 min read

Audits

Audits are normally carried out using the Qarma platform, but in case audits have to be imported from another source, here is the overall data structure that needs to be provided. This import API only supports creating audits in status Report and cannot be used for planning audits.

Audit data fields

Field

Description

Data type

Field

Description

Data type

start_time

The date and time for the start of the audit

Date (UTC)

end_time

The date and time for the end of the audit

Date (UTC)

supplier_name (optional)

Name of the supplier

String

supplier_number (optional)

The supplier number, needs to match the supplier numbers used in Qarma

String

auditor_name

Name of the person that performed the audit

String

auditor_email

Email address of the person that performed the audit. In Qarma, the email address is used to match users

String

production_unit_name

Name of the production unit that has been audited

String

production_unit_number

The production unit number, needs to match the production unit numbers used in Qarma

String

production_unit_address

The production unit address

String

latitude

GPS tracking of the audit location

Float

longitude

GPS tracking of the audit location

Float

accuracy

GPS tracking of the audit, the device will inform about accuracy of the position

Int

auditor_comment

The final summary provided by the auditor

String

checklist_name

This is the name of the template used for the audit

String

audit_type

Needs to match the audit types defined in Qarma

String

attachments

List of URLs for attachments to link to the audit. Attachments will be stored in Qarma at the time of import

List of URLs

audit_conclusion

The outcome of the audit (e.g. Failed, Passed, Below Expectation etc). This needs to match the audit conclusions defined in Qarma for the specific audit type

 

checkpoint_headers

A list of sections of the audit, for example Basic information, Workforce, Overtime, Safety etc.

Each header has a name and contains one or more checkpoints

checkpoints

For each checkpoint_header, there can be one or more checkpoints. Each checkpoint has several general fields:

  • status: Optional field can be Checked OK, Checked Not OK, Pending or Not Applicable.

  • comment: Text comment explaining the finding

  • images: A list of image URLs relating to this checkpoints. The URLs need to be accessible for Qarma to download during import

A checkpoint always has a type, which determines the additional information that it will include:

  • standard: will only have the general fields listed above.

  • multiple_choice: holds a list of options and which option(s) has been chosen by the audit. Each option have the following fields:

    • name: the name of this option

    • description: a longer text description of the option

    • color: a color code used for displaying in the report

    • score: each option can have a score, used for calculating the percentage of max scores that are achieved for each checkpoint header and the full audit itself. If score is omitted, it means selecting this option will remove the checkpoint from the max score calculations.

  • text: contains a list of key-value pairs with textual information

  • text_table: a list of two-dimensional matrices with header rows and columns. The values are strings.

Creation and update lifecycle

New records will only be created, if there is no existing audit matching on all four points:

  • Supplier number (fall back to supplier name if no number is provided)

  • Production unit number (fall back to production unit name if no number is provided. If no production unit is provided, it will only match on supplier number/name)

  • End date of audit (not the time of day, but only the date)

  • Audit type

If an existing audit is found, it will be updated with the information supplied. Please note that additional comments and conclusions set for the audit will not be cleared and will remain, even if the content of the audit changes.

Corrective Action Plan (CAP)

Corrective action plans are created as follow-up for audits to describe non-conformances that the production unit should improve on.

CAP data fields

The CAP is a list of corrective actions (CA); each corrective action contains the following information:

Field

Description

Data type

Field

Description

Data type

status

The status of the CA can be one of:

  • Open

  • In review

  • Closed

String

created_date

When the CA was created

Date (UTC)

due_date

When the CA is due for resolution

Date (UTC)

resolution_date

When the CA has been resolved

Date (UTC)

finding

The non-conformance that was identified

String

description

A full description of the finding, including information about the expected measures to be taken to resolve it.

String

resolution

A textual description of how the CA was resolved

String

creator

The email address of the person that created the corrective action

String

responsible

The email address of the person responsible for taking action (needs to match email address of a user in Qarma)

String

approver

The email address of the person who will approve the CA has been resolved (needs to match email address of a user in Qarma)

String

resolution_images

List of URLs for images that are taken as evidence that the CA has been resolved. Images will be downloaded and stored in Qarma at the time of import

List of URLs

resolution_attachments

List of URLs for files that are provided as evidence that the CA has been resolved. Files will be downloaded and stored in Qarma at the time of import

List of URLs

supplier

  • supplier_name (optional)

  • supplier_number (optional)

Name of the supplier and supplier number, needs to match the supplier numbers used in Qarma

String

production_unit

  • production_unit_name

  • production_unit_number

Name of the production unit, and production unit number, needs to match the production unit numbers used in Qarma

String

location

  • latitude

  • longitude

  • accuracy

  • timestamp

GPS tracking of the resolution images location

  • float

  • float

  • integer

  • DateTime

audit_id

The internal Qarma id of the audit that the CAP is following up on.

If the CAP is embedded in the audit data for creation, this part can be omitted.

If no audit_id is provided, the CAP will not be linked to an audit.

String

audit_end_time

Used to identify the audit, if the audit_id is not available. Most match the audit end_time down to milliseconds.

DateTime

audit_type

Used to identify the audit if the audit_id is not available.

String

groups

A list of groups matching groups in Qarma (used for controlling access)

List of strings

 

Creation and update lifecycle

New records will only be created, if there is no existing CA matching on all four points:

  • Supplier number (fall back to supplier name if no number is provided)

  • Production unit number (fall back to production unit name if no number is provided. If no production unit is provided, it will only match on supplier number/name)

  • CA creation date (not the time of day, but only the date)

  • Finding text (exact match)

If an existing CA is found, it will be updated with the information supplied.

Suppliers

This section describes both suppliers and production units.

Supplier data fields

Field

Description

Data type

Field

Description

Data type

supplier_name

Name of the supplier

String

supplier_number

The supplier number

String

groups

A list of groups matching groups in Qarma (used for controlling access)

List of strings

production_units

A list of production units for this supplier. The list needs to include all production units linked to the supplier (the full final state). When updating an existing supplier, any linked production units that are not included in the import data will be unlinked.

  • production_unit_number (required)

  • production_unit_name (optional)

Creation and update lifecycle

New records will only be created, if there is no existing supplier or production unit matching on:

  • Supplier number if provided

  • Supper name (only if no number if provided - note that fuzzy matching is applied to match names, The fuzzy matching removes all whitespaces, commas, and periods, and also downcases. So e.g.
    "Shanghai Factory, China" and “shanghaifactorychina” will match to the same supplier.

If an existing supplier is found, it will be updated with the information supplied.

 

Production Units

This section describes production units. Although production units can be created when updating or creating suppliers, the only way to update a production unit is through the following fields.

Note that production units can only be updated if the organization has unit production unit numbers.

Supplier data fields

Field

Description

Data type

Field

Description

Data type

production_unit_name

Name of the production unit

String

production_unit_number

The production unit number

String

production_unit_address

The address of the PU

String

location

The gps location of the PU

  • latitude

  • longitude

map

float

custom fields

Custom fields defined per organization in Qarma

Depends on which type of custom field (date, number, text, list)

status

The status of a production unit

String

upstream_production_units

A list of production units that supply to the current production unit. The list needs to include all upstream production units (the full final state). When updating an existing production unit, any linked production units that are not included in the import data will be unlinked.

  • production_unit_number (required)

  • production_unit_name (optional)

 

General notes

Omission of a field will mean that this field is not updated when matching an existing entity in Qarma. If fields need to be cleared, an empty value needs to be provided rather than omitting the field.