10.0.6 Importing contracts using CSV files

Import contract features

BigFix Inventory import contracts have the following features:

Allows you to create and modify contract details with data provided in a CSV file.
Contracts are identified using the contract ID.
Multiple software products can be added to a contract – one software product per CSV row. You can not delete a software product.
Software products, metrics and their relations specified in the CSV file must exist prior to the import.
Purchase orders are identified by Purchase Order Number.
Multiple purchase orders can be added to a contract or modified – one purchase order per CSV row. You can not delete a purchase order.
Custom field columns are prefixed with CUSTOM_, for example, “CUSTOM_My custom field”. The custom field column header is case sensitive.
CSV separator can be modified in the Advanced Server Settings with the “CSV report separator” (csvReportSeparator) property. Comma (‘,’) is default separator.

In case an import fails, import report appears with errors details.
CSV files must be encoded as UTF-8 (without BOM) format.
Only ASCII characters in contracts data are fully supported in BigFix Inventory version 10.0.6. The issue is not applicable since version 10.0.7. From BigFix Inventory 10.0.7, softwares which contains non-ASCII characters are accepted in contracts REST API, as well as in the search field on UI, and contract fields like contract name in REST API can contain non-ASCII characters.

Import through WebUI

To import using the WebUI, perform the following steps:

Click Reports > All Contracts. All Contracts page appears.
Click Edit and then select Import Contracts from the dropdown. Import contracts from CSV file dialog box appears.
Select a CSV file and click Import.

Import through API

Example API request:

curl -H "Content-Type: multipart/form-data" \ 
    -X POST \ 
    -F upload[contracts]=@c:\contracts.csv \ 
    https://localhost:9081/api/sam/v2/contracts/import?token=1234567890abcdef1234567890abcdef123456

CSV file format

Contracts can be imported from a CSV file. The following tables lists the column names available in the CSV file:


Column name	Description	Importance
Contract ID	Contract ID allows you to identify a contract. The purpose of this field is to identify main properties, such as type and metric of a contract. If a contract with specified ID already exists in BigFix Inventory, it is updated with the values from CSV file. If it does not exist, a new contract is created.	Mandatory
Name	Contract name	Mandatory
Metric ID	Metric ID For metric ID names, see also Metric IDs and code names.	Optional
Metric Code Name	If Metric ID column is present, the Metric Code Name value is ignored. For metric ID names, see also Metric IDs and code names.	Optional
Type ID	Number representing contract type, such as 1 - License, 2 - Support, 3 - Service, 4 - Hardware, and 5 – Other.	Required
Computer Group ID	Identifier of the computer group. When provided, Computer Group Name value is ignored.	Optional
Computer Group Name	When both Computer Group ID and Computer Group Name are not provided, then “All computers” group will be assigned. If no matching computer group is found, the CSV row is rejected. When there is more than one computer group with provided name, the CSV row is rejected. Note: Case sensitive	Optional
Threshold	Threshold value Note: Positive integer	Optional
Publisher Name	Publisher name is required only when Software Product Name is specified. The publisher must exist in BigFix Inventory before import.	Optional
Product Name	Name of the product. The product must exist in BigFix Inventory before import.	Optional
Purchase Order Number	Purchase order number	Optional
Purchase Order Document Link	Document link of the purchase order. If specified, requires Purchase Order Number to be present.	Optional
Purchase Order Vendor	Vendor of the purchase order. If specified, requires Purchase Order Number to be present.	Optional
Purchase Order Value	Purchase order value. Value is always a positive integer (including 0). ELA value can be set by specifying ELA or -1. If specified, requires Purchase Order Number to be present.	Optional. Required if Purchase Order Number value is provided
Purchase Order Entitlement Start	Entitlement start date of the purchase order. The allowed format is "YYYY-MM-DD", for example "2019-01-31". If specified, requires Purchase Order Number to be present	Optional. Required if Purchase Order Number value is provided.
Purchase Order Entitlement End	Entitlement end date of the purchase order. This value is optional. Allowed format is "YYYY-MM-DD", for example, "9999-12-31" or "Never". If specified, requires Purchase Order Number to be present.	Optional
Custom fields	Any number of optional columns representing contract custom fields. The fields must be already present in BigFix Inventory. When provided custom field is not found (does not exist), CSV import fails. Column names for custom fields are prefixed with "CUSTOM_", such as "CUSTOM_My Custom Field". Provided value type must match the type of the custom field. If the custom field is required, then the value must be provided.

Assumptions, limitations and restrictions of the CSV imports:

First row of the CSV file (header) contains field names.
Unused, optional columns can be omitted.
Import of the CSV adds new Software Products to a contract and does not remove existing entries.
Import of the CSV adds new or updates existing Purchase Order entries (matching on Purchase Order Number value) and does not remove existing entries.
In case multiple Software Products and/or Purchase Order need to be added, they need to be specified in separate rows (repeating the contract specific fields, like. name and computer group).
Column names and values need to be separated by a character specified in BigFix Inventory Advanced Server Settings with the “CSV report separator” (csvReportSeparator) property. Comma (‘,’) is default separator.
If column header or value contains a separator character, it needs to be enclosed in quotes.
CSV rows are processed in the order they are defined in the file. If one contract is defined in multiple rows, all values except Publisher Name, Product Name and Purchase Order fields should be repeated in every column. Otherwise, contract values updated by one row may be later modified by further rows. Subsequent imports of the same CSV file will produce the same outcome.
Purchase Order Document Link, Purchase Order Vendor, Purchase Order Value, Purchase Order Entitlement Start and Purchase Order Entitlement End columns can be present in the CSV file only when Purchase Order Number column is present.
A failure of importing a single contract row fails whole import. Already imported rows are rolled back.

Known issues

Custom fields for error messages are identified using the ID. The ID is retrieved using contracts API. To view the list of all custom fields, view the Contracts API.

CSV Example with multiple contracts

Contract ID, Name, Type ID, Threshold, Metric Code Name, Computer Group ID, Computer Group Name, Purchase Order Number, Purchase Order Value, Purchase Order Entitlement Start, Purchase Order Entitlement End, Product Name, Publisher Name, CUSTOM_contact person 
CO1, Contract 1, 3, 100, INTERNAL_INSTALL, 0, All Computers, PO1, 5000, 2021-08-03, 2030-05-20, Software 1, Publisher 1, Name
CO2, Contract 2, 2, 350, CLIENT, 0, All Computers, PO2, 2, 2019-05-21, 2025-06-21, Software 2, Publisher 2, Tom

CSV Example with multiple Purchase Orders and software products assigned to two contracts

Contract ID, Name, Metric Code Name, Type ID, Computer Group ID, Threshold, Publisher Name, Product Name, Purchase Order Number, Purchase Order Document Link, Purchase Order Vendor, Purchase Order Value, Purchase Order Entitlement Start, Purchase Order Entitlement End 
Contract 1, My contract 1, TICKETS,3,2,12, Publisher A, Sample Product A, PU001, www.test.com, My Vendor A,125,2019-03-03,2044-07-11 
Contract 1, My contract 1, TICKETS,3,2,12, Publisher A, Sample Product B, PU002,www.test2.com, My Vendor B,ELA,2020-03-03, 
Contract 1, My contract 1, TICKETS,3,2,12, Publisher B, Sample Product C
Contract 2, My contract 2, CLIENT,1,0,70, Publisher A, Sample Product B, PU003,www.test3.com, My Vendor C,200,2018-01-01,2021-12-28 
Contract 2, My contract 2, CLIENT,1,0,70,,, PU004, www.test4.com, My Vendor D, 100,2020-01-01, 2021-03-28