# Transfer Item BOMs

```{image} /img/workflows/vault_to_flc.png
:align: right
:width: 200px
```

This sample [Workflow](</workflows>) is meant to display how Vault Item metadata, attached Vault files as well as Bill Of Material information can be transferred to Fusion 360 Manage.\
It covers the most common user scenarios and is easy to configure but also serves as a base to create custom workflows.

**Note**: It pushes Vault items, their BOMs and attachments from Vault to Fusion 360 Manage.

:::{admonition} Requirements
:class: warning

The job and its configuration are designed for use with a **pre-configured Vault** and the Fusion 360 Manage **workspace named "Items"**.
```{image} /img/workflows/fusionmanage_items_workspace.png
:align: left
:width: 290px
```
```{image} /img/workflows/vault_to_flc_item_field_mapping_standard_Vault.png
:align: right
:width: 280px
```
In current Fusion 360 Manage tenants, the "Items" workspace is available by default.

If the workspace is missing on your tenant, add it via *Administration → Template Library* by installing the "Items Workspace" template.\
Then follow the configuration steps described [here](<getting_started/using_the_powerflc_workflows:result>).

In both cases, remember to adjust your ADMS hostname for the [Vault Thick and Thin Client](<getting_started/using_the_powerflc_workflows:result>) buttons to function property.\
Also adapt the ['Items onCreate onEdit' script](<getting_started:workspace behaviors>) to your Vault so that units, dimension fields, and weights are transferred for all items.


*Note:* Prior to 2024, Autodesk delivered customer tenants with a "*Vault Items and BOMs*" workspace or a workspace named "*Items and BOMs*". 
Find compatible configurations and appropriate jobs on [coolOrangeLabs](https://github.com/coolOrangeLabs/powerPLM/tree/main/Workflows/Sample.TransferItemBOMs%20-%20Vault%20Items%20and%20BOMs).


In the default configuration, several Vault Item Properties are expected, which may need to be created in Vault first!\
These are not included in standard Vaults, but you can use the Autodesk sample [PDMC Vault](<https://knowledge.autodesk.com/akn-aknsite-article-attachments/1d4dd4f8-74ec-4cf8-8e70-e4b5ac084be9.pdf>) to guarantee the expected settings.
:::

## Sample.TransferItemBOMs

This [powerJobs Processor Job](<inv:powerjobs_processor#jobprocessor/jobs>) performs all the succeeding Fusion 360 Manage requests by retrieving the e-mail address of the particular user that added the Job to the Queue.\
Therefore, follow the configuration steps described [here](<getting_started/using_the_powerflc_workflows:connect vault with fusion 360 manage>).

On the condition that the according [Workflow Trigger](<workflows/transfer_item_boms:triggering the workflow>) is configured, the job can easily be triggered from within the Vault Client by changing the lifecycle state of an item to *'Released'.*\
The job fails when the *'Sample.TransferItemBOMs'* workflow or the Fusion 360 Manage Workspace is not configured properly, when the Job Processor can't connect to the Fusion 360 Manage tenant or when invalid positions are detected in the Vault Item BOM. See [error handling](<inv:powerjobs_processor#jobprocessor/jobs:errors>).\
The job creates Fusion Lifecylce Items for the [$item](<inv:powerjobs_processor#jobprocessor/code_reference/objects/item>) where the Job is triggered on, and for all the Vault Items that are contained in its [Bill of Material](<getting_started:bill of materials>).\
All the configured [Item Details](<workflows/transfer_item_boms:item details>) will become filled with the mapped Vault data. If the corresponding Items already exist in Fusion 360 Manage, they will be updated with these configured values, but only if their description has changed since the last transfer.

When an item is transferred to Fusion 360 Manage that represents a *virtual component* which is used by an assembly, then the thumbnail shows the thumbnail of the assembly.\
The fields of the section *Primary File* in Fusion 360 Manage are empty, as there is no file equivalent existing for the Virtual Component.

Once a Vault Item is transferred to Fusion 360 Manage this relationship is stored in Vault Entity Attributes. They are not visible within Vault Explorer but can be retrieved e.g. in customizations by using the [Vault APIs](<inv:powervault#code_reference/objects/vault>):

```powershell

$vault.PropertyService.GetEntityAttributes($item.MasterId, 'FLC.ITEM') | Where-Object { $_.Attr -eq 'Urn' } | Select-Object -First 1 -ExpandProperty Val
#Returns "urn:adsk.plm:tenant.workspace.item:previewcoolorange.136.10610"
```

**Attachments:**\
By default the attachments of the following [Vault Item associations](<getting_started:attachments>) are configured to be downloaded into a temporary directory (by default `C:\Temp\`), then uploaded and linked in the [Attachments Tab](<https://help.autodesk.com/view/PLM/ENU/?guid=UG-ATTTAB-ATTACHMENTS>) of the Fusion 360 Manage Item:

- Vault Item attachments
- Composition association attachments (attachments of the primary  associated file)
- Design Document association attachments (attachments of the tertiary  associated files)
- Design Document DWGs (tertiary associated DWG files)

Already *existing attachments* in Fusion 360 Manage will *not be deleted* when the item is updated, although the attachment was removed from the item in Vault or the configuration settings have been changed.

**Bill of Materials:**\
For each [](<inv:powervault#code_reference/commandlets/get-vaultitembom>) component, a corresonding item will be created in Fusion Manage and linked in the [Bill of Materials tab](<https://help.autodesk.com/view/PLM/ENU/?guid=UG-BOMTAB-BOM>) of the header Item.\
The BOM line items and their BOM information will be updated if they already exist in the Fusion Manage BOM. Only line items that have been added manually to the Fusion Manage BOM remain untouched (determined using the `Source` field).\
When a BOM is created/updated by this job, following information is populated in Fusion Manage:

- BOM item structure from Vault
- Position (#)
- Quantity
- Mapped properties which are configured in the field mapping group [Vault BOM → FLC BOM](<getting_started:bill of materials>)

The `Bom_PositionNumber` property of the [](<inv:powervault#code_reference/objects/itembomrow>) in Vault is copied to the BOM field *Position Number*, and the `Bom_InstCount` is copied to the BOM *Quantity* field (both are not configurable!).\
Vault [ItemBomRows](<inv:powervault#code_reference/objects/itembomrow>) with identical `Bom_Number` properties are not unique and are getting merged within Fusion. The *Quantity* is determined from the sum of the Vault Instant Count values if the item occurs more than once. The *Qty Pos* is summed up from the Vault Quantity. Merged text fields with different values are set to "*Varies*". Numerical fields with different values are set to "-1".


## Configuration

The job is delivered with a default configuration file that has to be [imported](<configuration_manager:import / export workflows>) from the location *%ProgramData%\\coolOrange\\powerJobs\\Jobs\\Sample.TransferItemBOMs.json*.\
Once imported, the default configuration can be adjusted in the [Workflow-Settings](</configuration_manager/workflow_settings>) dialog.

```{image} /img/workflows/transfer_item_boms_configuration.png
:width: 600px
```

This workflow synchronizes Vault BOMs for the **Vault Entity Type** *Item* to the default **Fusion Manage workspace** *Items*.\
In Fusion Manage this workspace is already [configured properly](<getting_started:bill of materials>) and allows users to choose items from this workspace from within the *Bill of Materials Tab*.

However, you can also configure a different workspace and adapt the workflow to your Vault configuration. To do this, either remove the unneeded mappings or create the missing properties in Vault and/or Fusion Manage.

### Item Details

The fields in the [Item Details Tab](<http://help.autodesk.com/view/PLM/ENU/?guid=GUID-C2A1AEAB-227E-4A89-8972-CE779B7AFFA9>) get filled with the values of the mapped Vault properties, or the results of the mapped [Functions](<configuration_manager/workflow_settings:field mappings>).\
These mappings are transferred for all the Items which are created, and for those which already exist in Fusion 360 Mangage and will be updated.

Most of the mappings are configured in a [field mapping group](<configuration_manager/workflow_settings:field mappings>) named *Vault Item → FLC Item*.\
It contains the mappings between the properties of the Vault Item and the fields of the Item in Fusion 360 Manage:\
e.g. the *Fusion Lifecycle Item Field* `Number` gets filled with the value of the *Vault Property* `Number`, `Title` with `Title (Item,CO)`, `Description` with `Description (Item,CO)` and `Image` with `Thumbnail`.

Additional mappings can be found in the field mapping group *Vault primary Item-File Link → FLC Item*.\
It contains the Vault File properties which should be transferred from the primary subcomponent of the Vault Item to the fields of the Item in Fusion 360 Manage:\
e.g. the *Fusion Lifecycle Item Field*  `Primary File Name` gets filled with with the `Name` of the primary file that is linked to the Vault Item, `PDM Location` with the `Folder Path` and `Primary File Revision / Version` with its `Revision`.

#### Attachments

In order to configure what types of Vault Item associations will uploaded and attached to the Fusion 360 Manage Item the following [Workflow Settings](<workflows/transfer_item_boms:configuration>) can be adjusted:

| Type    | Name                               | Description                                                                                 |
|---------|------------------------------------|---------------------------------------------------------------------------------------------|
| Boolean | Upload Item Attachments            | Whether item attachments should be transferred to Fusion 360 Manage                         |
| Boolean | Upload Composition Attachments     | Whether attachments of the primary attached file should be transferred to Fusion 360 Manage |
| Boolean | Upload Design Document Attachments | Whether attachments of the design document file should be transferred to Fusion 360 Manage  |
| Boolean | Upload Design Document DWGs        | Whether design document native DWG files should be transferred to Fusion 360 Manage         |

#### Bill of Materials

The according behavior of how the Vault Item BOM gets transferred to Fusion 360 Manage can be adjusted with the following  [Workflow Settings](<workflows/transfer_item_boms:configuration>):

| Type          | Name                         | Description                                                                                                               |
|---------------|------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| FLC BOM Field | BOM-Source Field             | A BOM field in Fusion 360 Manage used to identify that the particular BOM row as been transferred by the workflow         |
| Text          | BOM-Source Value             | The value that identifies that the particular BOM row has been transferred by the workflow                                |

The mappings from Vault Bill of Materials properties to Fusion 360 Manage BOM fields can be configured in the  [field mapping group](<configuration_manager/workflow_settings:field mappings>) named *Vault BOM → FLC BOM*,\
e.g. the *Fusion Lifecycle BOM Field* `Row Order` with the *Vault Property* `Bom_RowOrder` and `Qty Pos` with `Bom_Quantity`.


The following fields are set by the job and **do not** need to be mapped:

| Fusion 360 Manage | Vault                                                    |
|-------------------|----------------------------------------------------------|
| Position          | BOM row Position Number                                  |
| Quantity          | BOM row Quantity                                         |
| Source            | "Vault" (depending on the *BOM-Source Value* setting)    |


## Triggering the workflow

In order to execute the workflow job on Vault Item lifecycle changes to a *'Released'* state, each single Vault lifecycle state transition must be extended to trigger a job of the type *"Sample.TransferItemBOMs"*:

```{image} /img/workflows/vault_lifecycle_customjob_transfer_item_bom.png
:width: 400px
```

Afterwards when changing the state for a specific Vault item, this will automatically queue the "Transfer Item BOMs" workflow job. Read more [here](<inv:powerjobs_processor#jobprocessor/jobs:queueing jobs>).

:::{note}
When the Lifecycle state gets changed to "*Released*" for the Vault Item and its dependent child Items, then the "*Sample.TransferItemBOMs*" job is automatically triggered for all of them.
:::

Alternatively the job can be queued within your own [client customization](<inv:powerevents#client_customizations>) using powerEvents and the [](<inv:powervault#code_reference/commandlets/add-vaultjob>) cmdlet, by passing the following [Item parameters](<inv:powerjobs_processor#jobprocessor/code_reference/objects/item:remarks>):

```powershell

$item = Get-VaultItem -Number 100018
$job = Add-VaultJob -Name "Sample.TransferItemBOMs" -Parameters @{"EntityId"=$item.Id;"EntityClassId"="Item"} -Description "Transfer Item BOMs for: $($item._Number)"
```

Also the *Priority* of the created Job can be configured this way. Jobs with higher priority will be executed first. The lower the number the higher the priority.