Configuration Provisioning

Configuration Provisioning enables SmartReader to automatically check for and download configuration updates from a cloud-based provisioning service. This feature allows centralized management of reader configurations, making it easier to deploy and update settings across multiple readers.

Overview

Configuration Provisioning provides:

• Automatic Updates: Periodically checks for configuration updates from a provisioning endpoint

• Version Management: Compares local and cloud configuration versions to determine if updates are needed

• Centralized Management: Manage reader configurations from a single cloud service

• Manual Triggers: Manually trigger provisioning checks via REST API

• Status Monitoring: Track provisioning status and last check results

How It Works

1. Background Service: A background service periodically checks the provisioning endpoint for updates

2. Version Comparison: The service compares the cloud configuration version with the local version

3. Automatic Update: If a newer version is available, it downloads and applies the configuration

4. Configuration Reload: The new configuration is saved and the application reloads it

Configuration

Configuration Provisioning is configured in appsettings.json under the Provisioning section:

{
  "Provisioning": {
    "Enabled": true,
    "EndpointUrl": "https://provisioning.example.com/api/config",
    "CheckIntervalHours": 24,
    "ApiKey": "your-api-key-here"
  }
}

Configuration Settings

Setting	Type	Description	Default
Enabled	boolean	Enable or disable configuration provisioning	false
EndpointUrl	string	URL of the provisioning endpoint	Required
CheckIntervalHours	integer	Hours between automatic checks	24
ApiKey	string	API key for authenticating with provisioning service	Optional

Provisioning Endpoint Requirements

The provisioning endpoint must:

1. Accept GET requests with a serial query parameter containing the reader serial number

2. Return JSON configuration in the format expected by SmartReader

3. Include a version field in the response for version comparison

4. Support authentication via API key (if configured)

Example Request:

GET https://provisioning.example.com/api/config?serial=370123456789

Example Response:

{
  "version": "1.2.3",
  "readerName": "R700-01",
  "antennaPorts": "1,2,3,4",
  "transmitPower": "1700,1700,1700,1700",
  ...
}

Manual Provisioning Check

You can manually trigger a provisioning check using the REST API:

curl -X POST \
  -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  https://<reader-ip>:8443/api/provisioning/check

Response:

{
  "success": true,
  "updated": false,
  "message": "Configuration is up to date or update failed"
}

• updated: true indicates that a new configuration was downloaded and applied

• updated: false indicates that no update was available or the check failed

Provisioning Status

Check the current provisioning status:

curl -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  https://<reader-ip>:8443/api/provisioning/status

Response:

{
  "enabled": true,
  "lastCheckTime": "2024-11-01T19:22:11Z",
  "lastCheckResult": "Success",
  "localVersion": "1.2.2",
  "cloudVersion": "1.2.3",
  "readerSerial": "370123456789",
  "errorMessage": null
}

Status Fields

• enabled: Whether provisioning is enabled

• lastCheckTime: ISO 8601 timestamp of the last check

• lastCheckResult: Result of the last check (Success, Failed, or NoUpdate)

• localVersion: Current local configuration version

• cloudVersion: Latest version available from the cloud

• readerSerial: Reader serial number used for provisioning

• errorMessage: Error message if the last check failed

Version Comparison

The provisioning service uses semantic versioning to compare configurations. A version is considered newer if:

• It has a higher major version number

• It has the same major version but a higher minor version

• It has the same major and minor versions but a higher patch version

Examples:

• 1.2.3 is newer than 1.2.2

• 1.3.0 is newer than 1.2.9

• 2.0.0 is newer than 1.9.9

Automatic Checks

When enabled, the provisioning service automatically checks for updates:

1. Initial Check: Performed 1 minute after application startup

2. Periodic Checks: Performed at the interval specified by CheckIntervalHours

3. Background Processing: Checks run in the background without blocking the application

Configuration Update Process

When a newer configuration is found:

1. The service downloads the configuration from the provisioning endpoint

2. The configuration is validated

3. The configuration is saved to /customer/config/smartreader.json

4. The configuration service reloads the new settings

5. The configuration is persisted to the database

6. The application continues running with the new configuration

Note: Configuration updates do not require an application restart. The new configuration is applied immediately.

Reader Serial Number

The provisioning service uses the reader's serial number to identify which configuration to retrieve. The serial number is:

• Retrieved from the reader's system configuration

• Included as a query parameter in provisioning requests

• Used by the provisioning service to return reader-specific configurations

You can retrieve the reader serial number via the provisioning API:

curl -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  https://<reader-ip>:8443/api/provisioning/serial

Response:

{
  "serialNumber": "370123456789"
}

Error Handling

The provisioning service handles errors gracefully:

• Network Errors: Logged and reported in status, but don't stop the service

• Invalid Configuration: Validation errors prevent configuration updates

• Missing Serial: Provisioning checks are skipped if serial number is unavailable

• Service Unavailable: Errors are logged and the service continues to run

Security Considerations

1. API Key: Use secure API keys for authentication with the provisioning service

2. HTTPS: Always use HTTPS for provisioning endpoints

3. Certificate Validation: Ensure proper SSL/TLS certificate validation

4. Network Security: Use secure networks or VPNs for provisioning connections

5. Access Control: Restrict access to provisioning endpoints

Best Practices

1. Enable Only When Needed: Keep provisioning disabled if not using a provisioning service

2. Set Appropriate Intervals: Balance update frequency with network usage

3. Monitor Status: Regularly check provisioning status to ensure updates are working

4. Version Management: Use semantic versioning for configuration versions

5. Test Before Production: Test provisioning updates in a development environment first

6. Backup Configurations: Keep backups of working configurations

7. Log Monitoring: Monitor provisioning logs for errors or issues

Troubleshooting

Provisioning Not Working

1. Check if Enabled: Verify Provisioning:Enabled is set to true

2. Verify Endpoint URL: Ensure the endpoint URL is correct and accessible

3. Check Serial Number: Verify the reader serial number is available

4. Review Logs: Check application logs for provisioning errors

5. Test Manually: Use the manual check endpoint to test provisioning

Configuration Not Updating

1. Check Versions: Verify the cloud version is newer than the local version

2. Check Status: Review provisioning status for error messages

3. Validate Configuration: Ensure the cloud configuration is valid JSON

4. Check Permissions: Verify file system permissions for configuration directory

Network Issues

1. Test Connectivity: Verify network connectivity to the provisioning endpoint

2. Check Firewall: Ensure firewall rules allow outbound HTTPS connections

3. Verify Proxy: If using a proxy, ensure it's configured correctly

4. Check DNS: Verify DNS resolution for the provisioning endpoint

API Reference

For complete API documentation, including all endpoints, request/response formats, and error codes, see the REST API documentation.

Related Features

• Configuration Overrides - Manual configuration management

• Backup/Restore - Configuration backup and restore

• REST API - Complete API reference for provisioning endpoints