Adding and updating contracts

10.0.6 Use /api/sam/v2/contracts.json API to add and update contracts.

PUT operation features

  • The request does not delete contracts and it does not remove contract's purchase orders or assignments to software. It merges data with the database content.
  • The operation matches metric by ID, or by code name if metric ID not provided. It creates a new metric if metric ID is not provided and metric code name is not found. The new metric has the same display name as code name from the request.
  • The operation does not create new software or publisher, unless createSoftware parameter is set to true (createSoftware=true).
  • The operation adds product-metric relation if needed.
  • The operation matches computer group by ID, or by name if ID is not provided. In case of no ID and no name, "All computers" group is used. Only computer groups of type "Reporting" can be used in contracts.

Example HTTP conversations

PUT /api/sam/v2/contracts.json
Adds or updates contracts provided in request body in JSON format (the format the same as the array under "rows" from GET request)
[
 {
   "contract_id":"CO1","name":"Contract1","type":2,"threshold":100,"metric":{"id":9,"code_name":"INTERNAL_INSTALL"},"computer_group":{"id":0,"name":"All Computers"}
  "purchase_orders":[{"purchase_number":"PO1","quantity":5000,"entitlement_start":"2021-08-03","entitlement_end":"2030-05-21"}
  {
   "purchase_number":"PO2","quantity":2,"entitlement_start":"2030-05-21"
   "entitlement_end":"2030-06-21"}],"software_products":
   [
   {"name":"Notepad++","publisher_name":"don.h@free.fr"}
   ]
  }
]

Limitations

Note: The limitations are applicable in BigFix Inventory version 10.0.6.
  • Error messages are displayed by default in language which is provided under "Accept-Language" header. The language selected in the user profile is not taken into account.
  • Custom field values must be provided in text format, such as "123" for integer type. This is not applicable to other fields.
  • PUT operation does not support national characters, such as Latin alphabets. To update or add contract data containing such characters, use CSV import or import using the UI. See also, Importing contracts.
  • 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, software 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.

Error codes

CODUI4040E=A contract with the specified name and type already exists
CODUI4041E=Some of the selected products are not assigned to the selected metric
CODUI4042E=A contract with the specified contract ID already exists
CODUI4043E=Purchase order numbers are not unique in this contract
CODUI4044E=Element {0} is missing in this contract
CODUI4045E=Incorrect JSON format. An array is expected.
CODUI4046E=Incorrect JSON format. The element at row {0} is not an object.
CODUI4047E=Required field {0} is empty
CODUI4048E=Required field {0} at row {1} is empty
CODUI4049E=Contract custom field with ID {0} does not exist
CODUI4050E=Product and publisher pair at row {0} is not found. Creating software option is not enabled.
CODUI4051E=Metric ID is not found
CODUI4052E=Specified metric code name is invalid. The field must contain up to 254 characters and can contain only uppercase letters, numbers, and the following characters: "-_".
CODUI4053E=Computer group with ID {0} is not accessible to the user or target contract computer group does not exist
CODUI4054E=Ambiguous computer group name. More than one matching group is found.
CODUI4055E=Field {0} at row {1} is too long. The maximal length is {2}.
CODUI4056E=Format of custom field with ID {0} is incorrect. Expected type: {1}
CODUI4057E=Custom field with ID {0} is required
CODUI4058E=Invalid contract type. Correct values are: 1,2,3,4,5.
CODUI4059E=Invalid contract threshold. The value must be a positive integer.
CODUI4060E=Field {0} is too long. The maximum length should be {1}.
CODUI4061E=Specified purchase order quantity at row {0} is invalid. The value must be a positive integer or -1 for ELA.
CODUI4062E=Specified purchase order entitlement dates at row {0} are invalid. End date cannot be before start date.
CODUI4063E=Format of field {0} at row {1} is incorrect. Expected type: {2}.
CODUI4064E=Software name at row {0} is already used by IBM bundle.
CODUI4065E=Software name at row {0} is already used by a software version or release of the same publisher.
CODUI4066E=Software at row {0} cannot be assigned to both Unknown metric and another metric.
CODUI4067E=Specified metric code name is not allowed.
CODUI4068E=Specified computer group name is not accessible to the user or target contract computer group does not exist.
CODUI4098E=Data conversion error occurred at row {0}. Ensure all fields have expected data types.
CODUI4099E=Contract processing failed. The contracts have not been imported.

# For Contracts import from CSV
CODUI5040E=Incorrect number of columns at row {0}.
CODUI5041E=Invalid header: {0}.
CODUI5042E=Invalid number: {0} at row {1} in column {2}.
CODUI5043E=Missing required column: {0}.
CODUI5044E=All or none of the columns need to be provided: {0}.
CODUI5045E=The {0} column requires {1} column to be present.
CODUI5046E=Missing value at row {0} in column {1}.
CODUI5047E=Values need to be provided for all or none of {1} columns at row {0}.