10.0.6 Importing contracts using CSV files

BigFix Inventory allows you to import contract data through API and Web UI.

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:
  1. Click Reports > All Contracts. All Contracts page appears.
  2. Click Edit and then select Import Contracts from the dropdown. Import contracts from CSV file dialog box appears.
  3. 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 Theshold 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