# Handhelds Devices Settings (Handheld Commons)

<p class="callout info">The **Handhelds Devices** section in OPSCOM allows administrators to manage and configure handheld devices used for enforcement and data collection. This includes registering new devices, pushing messages, and updating device settings, ensuring seamless operation for field personnel and accurate data synchronization.</p>

### Setup and Configuration

In order to use the handheld as a ticket writer, you will need to have the following permission set:

- **Display as Ticket Writer**: Ability to be a ticket writer on the Handheld Tablets or on the system.

This setting comes with the role Patrol Officer by default. To check if this role is set up in your system:

- Go to **System Configuration**, **Admin Management**, and click **Manage Roles**.
- Select the role for **Patrol Officer** and click on the tab for violations.
- You should see the box labeled **Display as Ticket Writer** checked.

[For more information on managing roles, click here!](https://opscom.wiki/books/setup-configuration-for-admins/page/manage-roles-and-permissions)

<p class="callout warning">Before accessing a handheld device for the first time, new admin users are required to log in through the online admin portal and complete their initial password reset.</p>

### Using this Feature

1. Click **Tools**, then **Handhelds Devices**. Alternatively, you can access this on the **Violations** menu as well.
2. The **Handhelds - Common Settings** screen appears, where you can manage various aspects of your handheld fleet. From here, you can edit settings such as ticket due dates, customize ticket footers, view device information, and add or manage individual handheld units.

##### <span style="text-decoration: underline;">Adding a New Device</span>

When adding a new handheld device, the process involves both the device itself and the OPSCOM system configuration.

1. **Install Software**: Start by installing the OPSCOM enforcement app on the handheld device.
2. **Obtain UUID**: After the first login attempt on the device, you'll receive a notice indicating the device isn't registered. This message will display a **UUID** (Universally Unique Identifier) number. This is a 16-digit alphanumeric code typically found under your login screen on the device.
3. **Register Device in OPSCOM**: 
    - Once on the **Handhelds - Common Settings** page in the admin portal, click **Add New Device**.
    - A new screen will open. You must add the following information: 
        - **UUID**: Enter the UUID obtained from the handheld device.

<p class="callout warning">You will need to include all characters in the UUID, **including dashes between the groups of characters. *Some UUIDs do not have dashes.***</p>

- - - **Server to Sync with**: **Always start by selecting the Production Server.** This is a critical step for initial device registration, regardless of whether the device will eventually be used for testing on a Preview server (explained further in "[Production Server First (Crucial)](https://opscom.wiki/link/191#bkmrk-production-server-fi)" under Best Practices &amp; Considerations).
        - **Name**: Enter a descriptive **name** to easily identify this device (e.g., "Patrol Unit 1," "Enforcement Officer John's Device").
        - Ensure the **Enabled** checkbox at the top of the entry form is selected.
    - Click **Add Device** once all information is in place.

##### <span style="text-decoration: underline;">Pushing Messages</span>

You can send messages directly to your configured handheld units:

1. On the **Handhelds - Common Settings** screen, click the **Push Message** button.
2. Follow the prompts to compose and send your message to the selected devices.

##### <span style="text-decoration: underline;">Updating Device Data</span>

To modify settings for an existing handheld device:

1. On the **Handhelds - Common Settings** screen, click on the **device name** you wish to update. This will open a drop-down list of editable settings.
2. Make your desired changes to the device's configuration.
3. Once finished, ensure you click **Process Updates** to save and apply your changes to the device.

<p class="callout info">To edit the ticket footer, you must have the permission level and role of Primary Admin.</p>

---

### <span style="color: rgb(22, 145, 121);">Best Practices &amp; Considerations</span>

- <span style="color: rgb(22, 145, 121);">**Production Server First (Crucial)**:</span>
    - <span style="color: rgb(22, 145, 121);">**Important Note**: Due to the underlying logic of the Handheld Common tool, you **must always register a new handheld unit on the Production admin portal first**, even if its ultimate purpose is for testing on a Preview site.</span>
    - <span style="color: rgb(22, 145, 121);">The system initially connects to the production server, then references the `PA Common/handheld assignment` table (which is written from production) to determine if a unit is registered for Production or Preview. This ensures the correct routing is established in the database.</span>
    - <span style="color: rgb(22, 145, 121);">This initial production-side registration is also why you can refresh preview sites without losing the handheld units configured for them.</span>
- <span style="color: rgb(22, 145, 121);">**Adding a Handheld Unit to Preview for Testing**:</span>
    1. <span style="color: rgb(22, 145, 121);">Start by **refreshing your preview** site to ensure it’s using the latest data. For details, see **[Create or Refresh a Preview Space](https://opscom.wiki/books/setup-configuration-for-admins/page/create-or-refresh-a-preview-space)**.</span>
    2. <span style="color: rgb(22, 145, 121);">First, add the handheld unit to **Handhelds - Common Settings** on the **production** admin portal as described in "Adding a New Device," but select your **Preview Server** in the **Server to Sync with** field. This sets the proper database route.</span>
    3. <span style="color: rgb(22, 145, 121);">Next, navigate to the **preview** admin portal and enter the exact same device information into its **Handhelds - Common Settings** section.</span>
    4. <span style="color: rgb(22, 145, 121);">Finally, perform a **reinstallation of the OPSCOM enforcement application** on the handheld device itself. This reinstallation allows the handheld to pick up the newly set path to the preview server.</span>
- <span style="color: rgb(22, 145, 121);">**Switching Between Production and Preview**:</span>
    - <span style="color: rgb(22, 145, 121);">Once a handheld entry exists in both Production (configured for Preview sync) and Preview, you can generally switch between environments by re-pointing the **Sync With** setting on both the Production and Preview admin portals to your preferred path.</span>
    - <span style="color: rgb(22, 145, 121);">**However, remember that you must perform a reinstallation of the software on the handheld unit each time you change the synchronization path in the system** for the handheld device itself to update with the selected path.</span>
- <span style="color: rgb(22, 145, 121);">**UUID Accuracy**: Ensure the UUID is entered precisely, as any error will prevent the device from connecting.</span>
- <span style="color: rgb(22, 145, 121);">**Descriptive Naming**: Use clear, identifiable names for your handheld devices to simplify management and troubleshooting.</span>