How to create SCR reports in the Nexar API

This guide contains information detailing creating SCR reports via the Nexar API. The data available through these reports is the same as that available via per-part SCR queries, but the delivery method and scale is different. SCR reports are designed for a large number of parts to be queried simultaneously, with input data provided in a .csv file, report generation taking longer and data returned in a .csv file. SCR part-level queries are designed for small numbers of parts to be queried at once, with data returned quickly and available within the GraphQL query response.

To be permitted to access SCR data, you must be signed up for an SCR Subscription and have remaining unused quota available. 

To receive a demo SCR Subscription or to sign up for an SCR subscription, contact us. For more information about how SCR can save your organization money, visit our web page.

SCR Subscriptions belong to Organizations and usage is metered annually on a unique part usage basis. This means that the same part can be queried multiple times within a year and it will only count as 1 unit of usage towards the quota. Both SCR reports and part-level SCR queries are metered using the same, shared SCR Subscription, so the same part queried via SCR report and via part-level query will only count as one unit of usage towards the quota.

TABLE OF CONTENTS

• Preparing your data
• The SCR Report
• Authentication
• Checking your usage
• Creating SCR reports
• Inputs:
• Checking SCR job status
  • Checking the state of a single report
  • Checking the state of multiple reports
  • Output from the queries
• Downloading SCR reports
• Deleting SCR reports

Preparing your data

Your part data is uploaded to the SCR service in a comma-separated values (.csv) file. This file must contain the following columns:

• Manufacturer part number (MPN) - the part number assigned by the manufacturer. Used with the manufacturer name to uniquely identify a part. For best results, ensure these are full MPNs, and any MPNs containing special characters (especially commas) are surrounded by double quotes.
• Manufacturer name - the name of the manufacturer of the part. Used with the MPN to uniquely identify a part. The articles here describe how to find a valid manufacturer name.
• Internal part number (PN) - an ID specific to your parts list that allows parts to be grouped (e.g. as a set of alternates). Parts with the same PN will be considered together in IPN Historical Procurability calculations (see below) but will otherwise be ignored. If you do not want to group parts, this can be a unique ID for the part (e.g. the line number in the file).
• Estimated Annual Usage (EAU) - the planned or estimated annual usage, in pieces, of your part. It is used to calculate the procurability of a part by comparing it to market availability. Our procurability calculations assume that you will not be able to purchase the entire stock from the market at any given time (as stock is often spread across several suppliers), and it also assumes you will not attempt to buy your entire annual usage in one buy. If you are attempting to purchase a year’s worth of usage in advance, we recommend increasing this to 200-400% of your annual usage. A part will be considered "procurable" if the stock level for the part is greater than or equal to the input EAU value.

Your input .csv file can contain extra columns, which will be ignored by SCR processing.

The SCR Report

Once an SCR job has been completed, it will create an SCR report file that can be downloaded. This report file is a .csv file containing SCR data for each part in your input .csv file that could be successfully identified. The returned .csv file is a copy of your input file, with extra columns of SCR data added to it. The columns included in the report include:

• Nexar Part ID - the Nexar/Octopart part ID associated with the part. If the part cannot be identified from the input MPN and Manufacturer name, then this ID will not be found, and no SCR data will be returned.
• Part Historical Procurability - This is a decimal figure between 0 and 1 indicating what proportion of days in the past 365 days a part’s globally available stock was above the EAU value. A value of 1 indicates that a part was above the threshold level for every day in the past year, whereas a value of 0 indicates that a part’s stock was below the threshold for every day in the past year.
• IPN Historical Procurability - This is a decimal figure between 0 and 1 indicating what proportion of days in the past 365 days the globally available stock of at least one part in an IPN group was above its EAU value. A value of 1 indicates that at least one part within an IPN group was above its threshold level for every day in the past year, whereas a value of 0 would indicate that the stock of all parts in the IPN group was below their threshold for every day in the past year.
• Count MPNs in IPN Historical Procurability - the number of parts included in the IPN group for IPN Historical Procurability calculations.
• Market Availability - These columns display the total global stock available at franchised distributors at weekly snapshots for the past 5 weeks. Due to data processing delays, the most recent date is usually about 2 days in the past.
• Octopart URL - a link to the part's page on octopart.com

Authentication

To generate SCR reports, check your usage and download reports. You will need to be authenticated. Please refer to our FAQs to find out more about our authentication.

Checking your usage

Before running an SCR query, you will want to check your current usage and quota limits to determine whether you can run the query. To do this, you will need to call the SCR Usage GraphQL query:

query ScrUsage {
  datScrUsage {
    countDistinctParts
    fromDate
    quota
  }
}

Creating SCR reports

Creating an SCR report is a two-step process:

1. Upload a file to the Nexar Files service, and store the returned GUID. See this article for guidance on uploading a file to the Nexar File Service.
2. Call the GraphQL mutation, datScrCreateJob, to create the run. This will run SCR calculations and create the report asynchronously. This operation will usually take several minutes, with larger parts lists taking longer to process.

mutation ScrCreateJob($fileId: String!) {
  datScrCreateJob(
    input: {
      fileId: $fileId
      label: "my-job-label"
      columnMapping: {
        pn: "Internal part ID"
        mpn: "MPN"
        manufacturer: "Manufacturer"
        eau: "Number of parts to purchase"
      }
    }
  ) {
    datScrJob {
      jobId
      userId
      label
      uploadDatetime
      jobState
      jobMessage
      runStats {
        numTotalParts
        numResolvedParts
      }
    }
    errors {
      ... on DatScrQuotaExceededError {
        usage
        quota
        message
      }
      ... on DatError {
        message
      }
    }
  }
}

Inputs:

• fileId - the file GUID returned from the Nexar Files service.
• label - an optional label to attach to an SCR job to allow you to identify SCR reports.
• columnMapping - a mapping to associate columns in your .csv input file with fixed column names that the SCR processing recognises. This input is optional, but if it is excluded, your column names must exactly match the recognised column names.

Payload:

• datScrJob - information about the SCR job
  • jobId - the ID created for this job. You will need to keep track of this to be able to query job results later
  • userId - the ID of the user that created the job
  • label - the label associated with the job in the inputs
  • uploadDateTime - the date-time that the run was started
  • jobState - the current state of the SCR job (see below for more details)
  • jobMessage - contains error or warning messages from the job run, if there are any
  • runStats - statistics about the SCR run. This will not contain any data until the run is complete.
• errors - allows any error information about an SCR job to be retrieved:
  • DatScrQuotaExceededError - if your usage has exceeded your quota, the SCR job will not run. This error contains information related to this, including your current usage and quota, as well as an error message
  • DatError - contains any other error messages relating to the SCR job (if there are any)

Checking SCR job status

As report creation is asynchronous, you will need to check on the progress of your SCR report runs after creating them. You can either check the state of a single SCR report or multiple SCR jobs.

Checking the state of a single report

To check the state of a single SCR job, you will have to have the jobId for that job and call the following GraphQL query:

query ScrJobState($myJobId: String!) {
  datScrJob (jobId: $myJobId) {
    jobId
    userId
    label
    uploadDatetime
    jobState
    jobMessage
    runStats {
      numTotalParts
      numResolvedParts
      numRestocked
      numDestocked
      numHpZeroParts
      numHpIntervalParts
      numHpOneParts
      numProc28dAgo
      numProc21dAgo
      numProc14dAgo
      numProc7dAgo
      numProcCurrent
    }
  }
}

query ScrJobStates($myJobIds: [String!]) {
  datScrJobs (jobIds: $myJobIds) {
    jobId
    userId
    label
    uploadDatetime
    jobState
    jobMessage
    runStats {
      numTotalParts
      numResolvedParts
      numRestocked
      numDestocked
      numHpZeroParts
      numHpIntervalParts
      numHpOneParts
      numProc28dAgo
      numProc21dAgo
      numProc14dAgo
      numProc7dAgo
      numProcCurrent
    }
  }
}

Output from the queries

The outputs from this query are the same as those in the datScrJob payload in the datScrCreateJob mutation. The outputs that are of more interest once the job has finished are:

• jobState - the current state of the SCR job, it can be one of four possible states:
  • COMPLETED - the job has finished successfully.
  • FAILED - the job has finished unsuccessfully. Check the jobMessage for more information on the failure.
  • RUNNING - the job has not finished yet
  • UNKNOWN - the state of the job is unknown. This might occur if the jobId can't be found, or if there has been an internal error.
• runStats - statistics about the SCR run. This will not contain any data until the run is complete.
  • numTotalParts - the total number of parts included in the input .csv file
  • numResolvedParts - the number of parts that were successfully identified from the input .csv file from the MPN and manufacturer
  • numRestocked - the number of parts that were unprocurable (stock < EAU) one week ago that are now procurable (stock >= EAU).
  • numDestocked - the number of parts that were procurable (stock >= EAU) one week ago that are now unprocurable (stock < EAU).
  • numHpZeroParts - the number of parts with a historical procurability value of 0
  • numHpIntervalParts - the number of parts with a historical procurability value between 0 and 1
  • numHpOneParts - the number of parts with a historical procurability value of 1
  • numProcNdAgo - the number of parts that were procurable (stock >= EAU) N days ago (N can be 7, 14, 21, or 28)
  • numProcCurrent - the number of parts that are currently procurable (stock >= EAU)

Downloading SCR reports

Once an SCR job has been completed, the report file can be downloaded. To download the file, you will need to call the following GraphQl query, with the jobId of the SCR job that created the report:

query ScrReport($myJobId: String!) {
  datScrReport (jobId: $myJobId) {
    jobId
    downloadUrl
  }
}

SCR reports may be deleted if you no longer need them. Note that once a report has been deleted, you can no longer access the report or any information about the SCR job. To delete an SCR report, you will have to call the following GraphQL mutation:

mutation DeleteSCRReport($myJobId: String!) {
  datScrDeleteJob(input: {jobId: $myJobId}) {
    datScrJob {
      userId
      jobId
      label
      uploadDatetime
      jobState
      jobMessage
    }
    errors {
      ...on DatScrCouldNotDeleteJobError {
        job {
          userId
          jobId
          label
          uploadDatetime
          jobState
          jobMessage
        }
        message
      }
      ...on DatError {
        message
      }
    }
  }
}