Package Name: ZPECloud-ZTP-Script.zip

Purpose

This document explains how to use the ZPE Cloud Custom Field Automation package to automatically create device custom fields from a CSV file using a ZPE Cloud Service Account.

The package allows administrators to:

• Bulk create custom fields
• Apply metadata to multiple devices
• Avoid manual device-by-device configuration
• Use a dedicated Service Account instead of personal credentials
• Eliminate MFA requirements for automation
• Generate an audit report of all actions performed

Package Contents

The folder should contain:

4

Example:

ZPECloud-ZTP-Script

│

├── zpecloud-test-auth.py

├── zpe_custom_fields_service_account.py

├── device_info.csv

│

└── nexservice@4acd461e6bf62751.zpecloud.com-api-key.txt

Solution Overview

The workflow is:

Create Service Account->Download API Key->Run Authentication Test->Update CSV->

Run Custom Field Script->Review Results Report

Service Account Creation

Recommended Authentication Method

When creating the Service Account select:

Authentication Method = API Key

Do NOT select:

OAuth 2.0

unless your organization specifically requires OAuth integration.

API Keys are easier to maintain and are the preferred method for automation jobs.

Create Service Account Page

Service Account Security Recommendations

Follow least privilege principles.

Grant only permissions necessary to:

Required

Read Devices

Read Device Information

Read Device Inventory

Read Custom Fields

Create Custom Fields

Avoid

User Administration

Service Account Administration

Company Administration

License Management

SSO Administration

Password Management

Organization Configuration

Why?

This script does only two things:

1. Reads device information
2. Creates custom device fields

The Service Account should have no permissions beyond those actions.

API Key Management

After creating the Service Account:

1. Generate API Key
2. Download API Key
3. Save TXT file

Example:

nexservice@4acd461e6bf62751.zpecloud.com-api-key.txt

Store Key File

Place the downloaded TXT file in the script folder.

Correct:

Keep the key with the scripts.

Configure the Script

Open:

zpe_custom_fields_service_account.py

Locate:

 Change if necessary.

Authentication Validation Test

Before making any API changes run the authentication test.

This validates:

• API key is valid
• Network connectivity exists
• Service Account permissions work
• Device inventory is accessible

No changes are made.

Running the Test Script

Windows

Open PowerShell:

cd "C:\Path\To\ZPECloud-ZTP-Script"

python .\zpecloud-test-auth.py

Linux

Shell

cd ZPECloud-ZTP-Script

python3 zpecloud-test-auth.py

macOS

Shell

cd ZPECloud-ZTP-Script

python3 zpecloud-test-auth.py

Expected Output

Example:

Understanding the Test Script

Many engineers ask:

Why does it only show one device?

This is expected.

The test script intentionally does:

Python

https://api.zpecloud.com/device?limit=1

The important part is:

limit=1

which means:

Return only one device.

Example response:

JSON

1

{

2

"count": 38,

3

"list": [

4

{

5

"hostname": "ELLIS-NGM"

6

}

7

]

8

}

Interpretation:

count = 38

means:

The Service Account can see 38 devices.

while

list

contains only one device because we specifically requested one.

What the Test Actually Proves

When you receive:

Status Code: 200

you have already confirmed:

✅ Service Account exists

✅ API Key works

✅ Bearer Token authentication works

✅ Connectivity to ZPE Cloud works

✅ Device permissions work

✅ Python requests can successfully query ZPE Cloud

The actual device displayed is not important.

Authentication Troubleshooting

Error: 401

Plain Text

Unauthorized

Possible causes:

• Expired API Key
• Invalid API Key
• Corrupted TXT file

Resolution:

• Regenerate Service Account API Key
• Download new TXT file

Error: 403

Forbidden

Possible causes:

• Service Account disabled
• Missing device permissions

Resolution:

• Verify Service Account status
• Verify assigned group permissions

Error: File Not Found

Example:

FileNotFoundError

Resolution:

Verify:

API_KEY_FILE

matches actual filename.

Error: Timeout

Example:

ReadTimeout

Resolution:

Verify:

• VPN
• Internet connectivity
• Firewall
• Proxy configuration

CSV Configuration

The first row contains field names.

Example:

CSV

serial_number,Location,Owner,Environment

All following rows contain values.

Example:

CSV

serial_number,Location,Owner,Environment

ABC123,Dallas,Network Team,Production

XYZ456,Chicago,Operations,Lab

CSV Rules

Column 1

Must contain:

Serial Number exactly matching the device serial number in ZPE Cloud.

Remaining Columns

Each additional column becomes a custom field.

Example:

CSV

serial_number,Site,Owner

Creates:

Site

Owner

custom fields.

Example Result

Input:

CSV

serial_number,Location

ABC123,Dallas

Produces:

Location = Dallas

on device:

ABC123

Running the Production Script

Windows

PowerShell

1

python .\zpe_custom_fields_service_account.py

Linux

Shell

1

python3 zpe_custom_fields_service_account.py

macOS

Shell

1

python3 zpe_custom_fields_service_account.py

What Happens During Execution

The script:

Step 1

Authenticates using the Service Account API Key

Step 2

Downloads device inventory

Step 3

Creates a serial-number-to-device-ID map

Step 4

Reads the CSV

Step 5

Checks whether custom fields already exist

Step 6

Creates missing custom fields

Step 7

Generates a report

Report Output

A report named:

custom_field_results.csv

is automatically generated.

Example:

CSV

serial,field,value,result

ABC123,Location,Dallas,CREATED

ABC123,Owner,Network Team,EXISTS

XYZ999,,,DEVICE_NOT_FOUND

Result Meanings

CREATED

Field was successfully created.

EXISTS

Field already existed.

DEVICE_NOT_FOUND

Serial number was not found.

FAILED

API operation failed.

ERROR

Unexpected exception occurred.

Validation After Execution

Validate:

Script Output1

Completed Successfully

Report File1

custom_field_results.csv

ZPE Cloud UI

Verify:

Device

→ Custom Fields

contains expected values.

Security Best Practices

Recommended

Use:

Dedicated Service Account

not personal accounts.

Recommended

Store API Keys in:

Protected folders

Password manager

Secrets manager

when moving to production automation.

Avoid

Sharing:

TXT files

Screenshots

Chat messages

Emails

containing API keys.

Change Control

Before updating production devices:

1. Save original CSV.
2. Test on one device.
3. Validate results.
4. Expand deployment.
5. Keep generated report.

FAQ

Do I need MFA?

No.

Service Accounts use API Keys.

Why doesn't the test script show all devices?

Because:

limit=1

intentionally requests one device.

Why use a Service Account?

Benefits:

• No MFA prompts
• No password expiration
• Easier auditing
• Safer automation

Can multiple engineers use the same package?

Yes.

Each engineer only needs:

zpecloud-test-auth.py

zpe_custom_fields_service_account.py

device_info.csv

and a valid Service Account API key TXT file.

Validation Checklist

Before execution verify:

• Service Account created
• API Key downloaded
• TXT file copied into folder
• API_KEY_FILE updated
• Authentication test returns 200
• CSV updated
• Script executed
• Report reviewed
• Device custom fields validated

See also:

https://support.zpesystems.com/portal/en/kb/articles/how-to-create-and-use-custom-fields