# 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 to be used with a pre-configured Vault and Fusion 360 Manage workspace.\
A specific workspace "**Vault Items and Boms**" is expected by the job:

- With **newer versions of the Fusion 360 Manage tenant** the **"Vault Items and Boms"** workspace is already installed by default.

- If the workspace is not available it can be be **installed** for the via *Administration → App Store*:

  > ```{image} /img/workflows/appstore_vaultitemsandboms_workspace.png
  > :width: 500px
  > ```

The job and default configuration is designed to be used with specific Vault settings:

- 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.

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 JobProcessor 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:**\
Foreach [](<inv:powervault#code_reference/commandlets/get-vaultitembom>) component an according Fusion 360 Manage Item will be created and linked in the [Bill of Materials tab](<https://help.autodesk.com/view/PLM/ENU/?guid=UG-BOMTAB-BOM>) of the Fusion 360 Manage header Item .\
The `Bom_RowOrder` property of the [](<inv:powervault#code_reference/objects/itembomrow>) will be copied to the BOM *Position Number* field unless configured differently, and the `Bom_InstCount` property to the BOM *Quantity* field.\
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".

The BOM line items and their BOM information will be updated if they already exist in the Fusion 360 Manage BOM. If a BOM line item was added manually to the Fusion 360 Manage BOM they are preserved (determined using the `Source` field).\
When a BOM is created/updated by the Job, following information is populated in Fusion 360 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>)

**Part List:**\
Optionally the Fusion 360 Manage [Part List Details Grid tab](<https://help.autodesk.com/view/PLM/ENU/?guid=UG-GRIDTAB-GRID>) gets populated with the raw Bill of Material from the selected Vault Item and the configured mappings within the field mapping group [Vault BOM → FLC Grid](<workflows/transfer_item_boms:part list>).\
In contrast to the Bill of Material information, identical item positions are **not merged**.

## 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 **Fusion 360 Manage Workspace** [Vault Items and Boms](</workflows/transfer_item_boms>).\
In Fusion 360 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*.\
The workflow is designed to be used with a pre-configured Vault and this Fusion 360 Manage workspace but can also be adapted to work with any other Vault/Fusion configuration by either deleting the unneeded mappings or by creating the properties in Vault and/or Fusion that are missing.

### 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 `Thumbnail` 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*  `File Name` gets filled with with the `Name` of the primary file that is linked to the Vault Item, `Folder` with the `Folder Path` and `File Version` with its `Version`.

#### 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                                                                                                               |
|---------------|------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| Boolean       | Use RowOrder as BOM Position | Whether the RowOrder from Vault should be used instead of the Position Number for the Position in a Fusion 360 Manage BOM |
| 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*.

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

| Fusion 360 Manage | Vault                                                    |
|-------------------|----------------------------------------------------------|
| Position          | BOM row Position or RowOrder (depending on the settings) |
| Quantity          | BOM row Quantity                                         |
| Source            | "Vault" (depending on the settings)                      |

#### Part List

The behavior of populating the Part List Details Grid can be adjusted with the following [Workflow Settings](<workflows/transfer_item_boms:configuration>):

| Type           | Name                                | Description                                                                                                                                                             |
|----------------|-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| FLC Grid Field | Grid ID Field                       | A Grid field in Fusion 360 Manage that identifies the Grid row (mapped Vault property value must be unique for each BOM row)                                            |
| Boolean        | Enable Grid Transfer                | Wheter the BOM information should be transferred to the 'Part List Details' grid. When set to 'false', the field mapping group *'Vault BOM → FLC Grid'* is not required |
| Boolean        | Transfer Grid only if BOM is merged | Whether the 'Part List Details' grid is only transferred when it contains merged BOM rows.                                                                              |

:::{warning}
  When the **Grid ID Field** setting is changed after items have already been created in Fusion 360 Manage issues can arise.
:::

Default mappings for Vault Bill of Materials properties to Fusion 360 Manage Part List Details fields are configured in the [Field mapping group](<configuration_manager/workflow_settings:field mappings>) named *Vault BOM → FLC Grid*,\
e.g. the *Fusion Lifecycle Grid Field* `Row Order` with the *Vault Property* `Bom_RowOrder`, `Number` with `Number`, `Quantity (Numeric Value)` with `Bom_Quantity` and `Pos Nr` with a numerically converted value of `Bom_PositionNumber`.

## 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.