Add reference information to devices, users, and organizations
Overview
Reference fields allow you to add descriptive information to devices, users, and organizations in your Code42 environment. This descriptive information can be used to add additional context for administrators, and also to integrate with external systems.
This article describes how to use the reference fields from both the Code42 console and the Code42 API.
Reference fields
The Code42 platform supports the following reference fields for devices and users. In Incydr Basic, Advanced, and Gov F1, you can also add this information to organizations.
- External Reference: Intended for optional external reference information, such as a serial number, asset tag, employee ID, or help desk issue ID.
- Notes: Intended for optional descriptive information.
Considerations
The examples in this article use the command line tool curl
to interact with the Code42 API. For a list of tools that can be used to interact with the API, see Tools for interacting with the Code42 API.
Use the Code42 console to edit reference information
Incydr Professional, Enterprise, Horizon, and Gov F2
Incydr Basic, Advanced, and Gov F1
Use the Code42 API to add reference information
Consider using the Code42 API to add reference information if you need to:
- Add reference information for many devices, users, or organizations in your Code42 environment via scripting.
- Configure an external system in your environment to automatically set reference information.
The examples below illustrate how to set the reference information for one user, device, or organization at a time. If you want to set values for many items at once, use the examples as the basis for a custom script. In the examples below:
- Replace console.us.code42.com with the base URL you use to access your Code42 cloud instance.
- Replace
<auth_token>
with an authentication token.
Use the Code42 API to add reference information for a device
The Code42 API Computer
resource allows you to set the computerExtRef
and notes
parameters for a device.
- Find a device's
guid
using one of these methods:- Search by the
userUid
of the user that owns the device:Copied!curl -X GET 'https://console.us.code42.com/api/v1/Computer?userUid=<userUid>' -H 'Authorization: Bearer
<auth_token>
' | python3 -mjson.tool - Search for the device by
name
:Copied!curl -X GET 'https://console.us.code42.com/api/v1/Computer?q=<name>' -H 'Authorization: Bearer
<auth_token>
' | python3 -mjson.tool
- Search by the
- Locate the device's
guid
in the output. For example:"guid": "681099810721783680"
- Set the
computerExtRef
andnotes
parameters for the appropriate deviceguid
:Copied!curl -X PUT -d '{ "computerExtRef": "Asset 410", "notes": "A note about the device" }' -H 'Content-Type: application/json' 'https://console.us.code42.com/api/v1/Computer/<guid>?idType=guid' -H 'Authorization: Bearer
<auth_token>
' | python3 -mjson.tool -
Examine the output of the command to verify that
computerExtRef
andnotes
contain the correct values.
Use the Code42 API to add reference information for a user
The Code42 API User
resource allows you to set the userExtRef
and notes
parameters for a user.
- Find a user's
userUid
using one of these methods:- Search for the user by email address:
Copied!
curl -X GET 'https://console.us.code42.com/api/v1/User?email=<email_address>' -H 'Authorization: Bearer
<auth_token>
' | python3 -mjson.tool - Search for the user by username:
Copied!
curl -X GET 'https://console.us.code42.com/api/v1/User?username=<username>' -H 'Authorization: Bearer
<auth_token>
' | python3 -mjson.tool - Search for the user by first and last name:
Copied!
curl -X GET 'https://console.us.code42.com/api/v1/User?q=<firstname>&&<lastname>' -H 'Authorization: Bearer
<auth_token>
' | python3 -mjson.tool
- Search for the user by email address:
- Locate the user's
userUid
in the output. For example:"userUid": "fa1633c3e5507360"
- Set the
userExtRef
andnotes
parameters for the appropriateuserUid
:Copied!curl -X PUT -d '{ "userExtRef": "ID040189", "notes": "A note about the user" }' -H 'Content-Type: application/json' 'https://console.us.code42.com/api/v1/User/<userUid>?idType=uid' -H 'Authorization: Bearer
<auth_token>
' | python3 -mjson.tool - Examine the output of the command to verify that
userExtRef
andnotes
contain the correct values.
Use the Code42 API to add reference information for an organization
The Code42 API Org
resource allows you to set the orgExtRef
and notes
parameters for an organization.
- Find the organization's
orgUid
by searching for its name:Copied!curl -X GET 'https://console.us.code42.com/api/v1/Org?q=<organization_name>' -H 'Authorization: Bearer
<auth_token>
' | python3 -mjson.tool - Locate the organization's
orgUid
in the output. For example:"orgUid": "691968598454770525"
- Set the
orgExtRef
andnotes
parameters for the appropriateorgUid
:Copied!curl -X PUT -d '{ "orgExtRef": "An organization identifier", "notes": "A note about this organization" }' -H 'Content-Type: application/json' 'https://console.us.code42.com/api/v1/Org/<orgUid>?idType=orgUid' -H 'Authorization: Bearer
<auth_token>
' | python3 -mjson.tool - Examine the output of the command to verify that
orgExtRef
andnotes
contain the correct values.