# Linking objects

QBI maintains a set of links, a "map" between AyaNova and QuickBooks Items in order to synchronize them and invoice work orders.

Linking is the process of telling QBI which _existing_ AyaNova object is linked to which _existing_ QuickBooks Item.

If an object doesn't exist on one side or the other then you must manually create them or using QBI export them to the other side via the [Export from AyaNova](linksync-export-from-ayanova.md) or [Export from QuickBooks](linksync-export-from-qb.md) features.

## Manual linking

Manual linking here means selecting individual items by hand from one side to link to an item on the other side.

### When to use manual linking

This is appropriate to use when:

-   Existing Customers in AyaNova are actually billed to a head office that is entered in QuickBooks

    So you would want multiple AyaNova Customers mapped (linked) linked to one QuickBooks customer (which is the one office that all these AyaNova Customers get their invoices sent to).

-   You have manually entered some data in AyaNova that may not have the exact same name as the name in QuickBooks so the [automatic link](#automatic-linking) Auto-Link feature would not work

-   You want full control over what existing AyaNova data is linked to what existing data in QuickBooks

### How to manually link

Using the "Link and Synchronize" menu option from the main menu:

![link and sync menu option](img/main-menu-tools-link-and-sync-item.png)

to open the "Link & Sync" form:

![link and sync form](img/link-sync.png)

Cached lists of AyaNova objects are displayed on the left side in a table and cached lists of QuickBooks items are displayed in the right side table.

#### Existing links

AyaNova objects that are linked will show the name of the QuickBooks item to which they are linked in the "Linked to" column (AyaNova objects can only be linked to a single QuickBooks item) and QuickBooks items that are linked will show a checkmark in the "Linked" column. The QuickBooks side shows a checkmark instead of the name of objects because any number of AyaNova objects can be linked to a single QuickBooks item (but not the other way around).

#### Select an object type

In this form you select the type of AyaNova object you want to work with from the "Object type" menu option:

![link menu object type](img/link-menu-object.png)

When you select an object type the data tables will change to show objects of that type in AyaNova and one or more types of Items from QuickBooks that potentially match the AyaNova type.

#### Selecting Rows to link

Rows of objects must be selected in order to make new links or change existing ones.

You can select rows in either table but not both at the same time.

You can select multiple rows in the AyaNova table because you can link multiple AyaNova objects to a single QuickBooks Item.

You can select a single row at a time in the QuickBooks table because you can only link one QuickBooks item to a single AyaNova object.

An entire row must be selected, it is not sufficient to select a single cell in the table.

Rows are selected by clicking on their row header:

![select rows](img/grid-select-rows.png)

Individual rows can be selected by holding down the Control key while clicking on each separate row to be selected.

You can also click on a row selector and drag up or down to select mutltiple contiguous rows.

If you simply want to select _all_ rows you can click on the header row selector at the top:

![select all rows](img/grid-select-all.png)

#### Selecting an object to link to

Once you have selected your row(s) to be linked choose the "Link selected items" menu option:

![link menu option](img/link-menu-link.png)

#### Link from AyaNova

If you have selected rows in the AyaNova table then you will be presented with options to link to a QuickBooks Item:

![link to qb](img/link-to-qb.png)

Here you can choose a QuickBooks item to link to from the drop down list box or place a checkmark in the "Nothing / remove link" to remove any existing links the selected AyaNova objects might have.

Once you make your selection select "OK" to continue. You will be prompted to confirm your choice before the link is made:

![link to qb confirm](img/link-to-qb-confirm.png)

Select OK to save the link choices or "Cancel" to back out.

#### Link from QuickBooks

If you have selected a row in the QuickBooks table then you will be presented with options to link to an AyaNova object:

![link to aya](img/link-to-aya.png)

Here you can choose a AyaNova object to link to from the drop down list box or place a checkmark in the "Nothing / remove link" to remove any existing links the selected AyaNova objects might have.

Once you make your selection select "OK" to continue. You will be prompted to confirm your choice before the link is made, select OK to save the link choices or "Cancel" to back out.

## Automatic linking

Automatic linking here means allowing QBI to make the links by comparing the names of objects and linking when there are exact matches.

### When to use Automatic linking

Any time there are matching objects already present on both sides such as:

-   you previously used an older version of QBI or AyaNova and just upgraded
-   after importing older AyaNova data into a newer version
-   after [deleting the QBI integration object](https://www.ayanova.com/docs/adm-integrations/#delete) from AyaNova
-   you have manually entered objects with the exact same names to either side

### What happens when automatic linking

QBI goes through the list of AyaNova objects displayed and if they are not currently linked compares the name to the QuickBooks items displayed and if a name matches _exactly_ it makes the link.

The automatic link does not update information from one object to the other - it links the two objects only.

The automatic link does not compare other fields of information for the object - only the name.

### How to automatically link

Using the "Link and Synchronize" menu option from the main menu:

![link and sync menu option](img/main-menu-tools-link-and-sync-item.png)

to open the "Link & Sync" form:

![link and sync form](img/link-sync.png)

Cached lists of AyaNova objects are displayed on the left side in a table and cached lists of QuickBooks items are displayed in the right side table.

#### Select an object type

In this form you select the type of AyaNova object you want to work with from the "Object type" menu option:

![link menu object type](img/link-menu-object.png)

When you select an object type the data tables will change to show items of that type in AyaNova and one or more types of items from QuickBooks that potentially match the AyaNova type.

#### Start the auto link process

Select the "Auto link" menu item:

![link menu auto link](img/link-menu-autolink.png)

QBI will immediately attempt to link the displayed items and update the display once completed.

## How to unlink and remove links

To remove existing links use the same process as when manually linking AyaNova objects to QuickBooks Items: follow the [Link from AyaNova](#link-from-ayanova) steps in the [manual linking process above](#how-to-manually-link) selecting the AyaNova objects to be unlinked and choosing "Nothing / remove link" when prompted to choose a QuickBooks Item.

## What happens if I delete a linked object

When QBI starts or when you refresh the cached data, QBI automatically checks existing links to ensure they are still valid.

If an object is not found you will be prompted to remove it's link in QBI:

![missing link prompt](img/missing-link-prompt.png)

If you select Yes the item will be unlinked.

If you select No QBI will go on to the next mismatch in the list if any.

If you select Cancel QBI will abort the startup and shut down.

Do note that if you delete or set to inactive something in QuickBooks after you have already successfully logged into QBI, as QBI will already have its populated cache of QuickBooks items - QBI will not know that you have since deleted or set to inactive until you have refreshed the cached data or restart QBI.
