How to setup basic Actions workflow

How to setup a basic Actions workflow

This demo shows how to setup a basic Actions workflow. This example uses design files from our Altium Demo.

Background

This demo will help you create an Action Workflow that calls the generate_bom Add-on that generates a BOM.csv from an Altium .prjpcb file.

The repository is located https://hub.allspice.io/Actions/generate-bom-altium

To run this demo, migrate our Actions-Demo repo and enable actions in your repository settings. Trigger the Workflow by creating an issue or pushing a file to the repo.

Workflow

This workflow file demonstrates how to call an Add-on and store the data in an Artifact. The comments in the file describe the functionality of each line.

02-Running-common-Actions.yml

# AllSpice Actions demo
# Action triggers on push and issues
# Action runs "generate-bom-altium" action
# .allspice/workflows/generate_bom.yml
name: Generate BOM
on:
  push:
  issues:
    types: [opened, closed, reopened]

jobs:
  Generate_BOM:
    runs-on: ubuntu-latest
    steps:
      - name: Generate BOM
       # Uses the "generate-bom" action at version v0.4 to generate BOM
        uses: https://hub.allspice.io/Actions/generate-bom@v0.4
        with:
          # The path to the Altium project file in your repo.
          source_path: Archimajor.PrjPcb
          
          # [optional] A path to a YML file mapping columns to the component attributes
          # This file must be provided.
          # Default: 'columns.yml'
          columns: .allspice/columns.yml
          
          # [optional] The path to the output file that will be generated.
          # Default: 'bom.csv'
          output_file_name: bom.csv
          
          # [optional] A comma-separated list of columns to group the BOM by. If empty
          # or not present, the BOM will be flat.
          # Default: ''
          group_by: 'Part Number'
          
          # [optional] The variant of the project to generate the BOM for. If empty
          # or not present, the BOM will be generated for the default variant.
          # Default: ''
          variant: ''

      # Print bom.csv to terminal
      - name: Show BOM
        run: cat bom.csv

      - name: Upload file as artifact
        uses: actions/upload-artifact@v3
        with:
          name: BOM.csv
          path: bom.csv

Customizing the Attributes Extracted by the BOM Script

This script relies on a columns.yml file. This file maps the Component Attributes in the SchDoc files (right) to the columns of the BOM (left).

An example for Altium columns.yml file content is:

columns:
  - name: "Manufacturer"
    part_attributes:
      - "Manufacturer"
      - "MANUFACTURER"
  - name: "Part Number"
    part_attributes:
      - "PART"
      - "MANUFACTURER #"
      - "_part_id"
  - name: "Designator"
    part_attributes: "Designator"
  - name: "Description"
    part_attributes:
      - "PART DESCRIPTION"
      - "_description"

In this file, the keys are the names of the columns in the BOM, and the values are a list of the names of the attributes in the SchDoc files that should be mapped to that column. For example, if your part number is stored either in the PART or MANUFACTURER # attribute, you would add both of those to the list. If there is only one attribute, you can omit the list and just use a string. The script checks these attributes in order, and uses the first one it finds. So if both PART and MANUFACTURER # are defined, it will use PART.

An example for OrCad columns.yml file content is:

columns:
  - name: "Part Number"
    part_attributes:
      - "Part Number"
      - "_name"
  - name: "Designator"
    part_attributes: "Part Reference"
  - name: "Type"
    part_attributes: "Part Type"
  - name: "Value"
    part_attributes: "Value"

Note that py-allspice also adds a few static attributes, which are taken from the part itself, and not from the properties or attributes. For Altium projects, _part_id and _description are available, which correspond to the Library Reference and Description fields of the component. For OrCAD projects, _nameis available, which corresponds to the name of the component.

The underscore is added ahead of the name to prevent these additional attributes from overriding any of your own.

Where the BOM generation will use the attribute "PART DESCRIPTION" if it exists for a given component, and "_description" otherwise. Same for "PART" and "_part_id".

By default, the script picks up a columns.json file from the working directory. If you want to keep it in a different place, or rename it, you can pass the --columns argument to the script to specify where it is.

Group By

You can also group lines by a column value. The most common is _part_id. You can combine this with the columns json example above, like so:

- name: Generate BOM
  uses: https://hub.allspice.io/Actions/generate-bom@v0.4
  with:
    project_path: Archimajor.PrjPcb
    columns: .allspice/columns.json
    group_by: 'Part ID'

Which will generate a BOM squashed by components with matchin Part IDs.

Variants

To generate the BOM for a variant of the project, pass the --variant argument to the script. For example:

- name: Generate BOM
  uses: https://hub.allspice.io/Actions/generate-bom@v0.4
  with:
    project_path: Archimajor.PrjPcb
    columns: .allspice/columns.json
    output_file_name: bom-lite.csv
    variant: 'LITE'

When no variant is given, the BOM is generated without considering any variants.

View Actions results

After clicking on your workflow, you should see the results screen.

You can click on each job step to see more details.

• Set up job: This is boilerplate setup, is automatic, and can be ignored

• Generate BOM: This is the output from the Action script

• Show BOM: This is the contents of BOM.csv

• Upload file as artifact: This shows information regarding uploading the file BOM.csv as an artifact file for future use or reference. May be used in other Actions.

• Complete job: This is automatically generated and can be ignored.