- 4 Minutes to read
- Print
- DarkLight
- PDF
How to setup basic Actions workflow
- 4 Minutes to read
- Print
- DarkLight
- PDF
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, _name
is 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.
![generate bom actions tab.gif Actions demo gif](http://cdn.document360.io/3d44af5c-3f49-4ca5-b152-10836a885c13/Images/Documentation/generate bom actions tab.gif)