arazzo: 1.0.1
info:
  title: Autodesk Calculate Embodied Carbon from a Regional Dataset
  summary: Find a sustainability dataset, locate a regional emission record, read its factor, and calculate emissions.
  description: >-
    Turning a quantity from a design into a defensible carbon number. The workflow
    finds the right sustainability dataset for the impact category, locates the
    emission record for the correct region and year, reads that record's emission
    factor and unit, and calculates total emissions for a quantity. The record is
    resolved before the calculation so the result is traceable to a named data
    provider, region, and vintage rather than an anonymous constant. Every step spells
    out its request inline so the flow can be read and executed without opening the
    underlying OpenAPI description.
  version: 1.0.0
sourceDescriptions:
- name: sustainabilityDataApi
  url: ../openapi/autodesk-sustainability-data-openapi.yml
  type: openapi
workflows:
- workflowId: calculate-regional-emissions
  summary: Resolve a regional emission factor and calculate emissions for a quantity.
  description: >-
    Lists datasets of the requested type, finds the record matching region, category,
    and year, reads the record to capture its emission factor and unit, and submits a
    calculation for the supplied quantity.
  inputs:
    type: object
    required:
    - datasetType
    - region
    - quantity
    properties:
      datasetType:
        type: string
        description: >-
          The dataset type to search: electricity, material, transportation, or
          construction.
      region:
        type: string
        description: Region or country code the emission factor must apply to.
      category:
        type: string
        description: Category to narrow the record search within the dataset.
      year:
        type: integer
        description: Data vintage year the factor should come from.
      quantity:
        type: number
        description: >-
          The quantity to calculate emissions for, in the unit the record specifies.
  steps:
  - stepId: findDataset
    description: >-
      List the datasets of the requested impact type and take the first. Each dataset
      names its data provider and version, which is what makes the resulting number
      auditable.
    operationId: getDatasets
    parameters:
    - name: filter[type]
      in: query
      value: $inputs.datasetType
    - name: page[limit]
      in: query
      value: 25
    successCriteria:
    - condition: $statusCode == 200
    - context: $response.body
      condition: $.data.length > 0
      type: jsonpath
    outputs:
      datasetId: $response.body#/data/0/id
      datasetName: $response.body#/data/0/name
      provider: $response.body#/data/0/provider
      version: $response.body#/data/0/version
  - stepId: findRecord
    description: >-
      Find the emission record for the target region, category, and year. Emission
      factors are strongly regional, so a factor from the wrong grid or the wrong year
      is simply the wrong answer.
    operationId: getRecords
    parameters:
    - name: datasetId
      in: path
      value: $steps.findDataset.outputs.datasetId
    - name: filter[region]
      in: query
      value: $inputs.region
    - name: filter[category]
      in: query
      value: $inputs.category
    - name: filter[year]
      in: query
      value: $inputs.year
    - name: page[limit]
      in: query
      value: 25
    successCriteria:
    - condition: $statusCode == 200
    - context: $response.body
      condition: $.data.length > 0
      type: jsonpath
    outputs:
      recordId: $response.body#/data/0/id
      records: $response.body#/data
  - stepId: readRecord
    description: >-
      Read the record to capture the emission factor, its unit, and the unit the
      quantity must be expressed in before any calculation is submitted.
    operationId: getRecord
    parameters:
    - name: datasetId
      in: path
      value: $steps.findDataset.outputs.datasetId
    - name: recordId
      in: path
      value: $steps.findRecord.outputs.recordId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      recordId: $response.body#/id
      recordName: $response.body#/name
      unit: $response.body#/unit
      emissionFactor: $response.body#/emissionFactor
      emissionFactorUnit: $response.body#/emissionFactorUnit
      gwp: $response.body#/gwp
  - stepId: calculate
    description: >-
      Calculate total emissions for the quantity against the resolved record, passing
      the unit the record itself declares so the arithmetic cannot be done against a
      mismatched unit.
    operationId: calculateEmissions
    requestBody:
      contentType: application/json
      payload:
        datasetId: $steps.findDataset.outputs.datasetId
        recordId: $steps.readRecord.outputs.recordId
        quantity: $inputs.quantity
        unit: $steps.readRecord.outputs.unit
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      totalEmissions: $response.body#/totalEmissions
      unit: $response.body#/unit
      emissionFactor: $response.body#/emissionFactor
  outputs:
    datasetId: $steps.findDataset.outputs.datasetId
    provider: $steps.findDataset.outputs.provider
    recordId: $steps.readRecord.outputs.recordId
    totalEmissions: $steps.calculate.outputs.totalEmissions
    unit: $steps.calculate.outputs.unit