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

Sign in to the Code42 console.
From Administration > Environment, select Devices or Users.
Click the name of the device or user.
Click Reference to view any existing reference information.
Click Edit to add or update reference information.
- Use External reference to record optional external reference information like serial numbers, asset tags, or employee IDs.
- Enter any Notes about the device or user.
- Click Save to save your changes.

Incydr Basic, Advanced, and Gov F1

Sign in to the Code42 console.
From Administration > Environment, select Devices, Users, or Organizations.
Click the name of the device, user, or organization.
From the action menu, select Edit.
Click Reference.
Configure the reference fields for the device, user, or organization:
- External Reference
- Notes
Click Save.

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.

Code42 Developer Portal
See the Code42 Developer Portal for more API documentation and resources. The portal provides:

A single access point for documentation of methods for Incydr, including Code42's REST API, Python SDK py42, and command-line interface (CLI)
A single request URL for Code42 API calls to each cloud instance
API reference documentation

Use the Code42 Developer Portal for your API needs as much as possible. APIs in the portal are the preferred way to integrate with Code42 for Incydr users. If you use Code42 APIs that do not appear on the Code42 Developer Portal, contact our Customer Champions for guidance on the best way to integrate with Code42.

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:

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:

curl -X GET 'https://console.us.code42.com/api/v1/Computer?q=<name>' -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Locate the device's guid in the output. For example:
```
"guid": "681099810721783680"
```

Set the computerExtRef and notes parameters for the appropriate device guid:

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 and notes 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:

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:

 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:

curl -X GET 'https://console.us.code42.com/api/v1/User?q=<firstname>&&<lastname>' -H 'Authorization: Bearer <auth_token>' | python3 -mjson.tool

Locate the user's userUid in the output. For example:
```
"userUid": "fa1633c3e5507360"
```

Set the userExtRef and notes parameters for the appropriate userUid:

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 and notes 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:

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 and notes parameters for the appropriate orgUid:

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 and notes contain the correct values.