Migrate from v1

This guide covers migration from the legacy v1 standalone agent (global flags) to the current Standalone collector (ms_teams_observability with sub-commands).

Major Changes

Topic	v1	Standalone
CLI	Global flags (--config, --ignore_state, …)	Sub-commands (run, validate, migrate-config, service, state, test-connection)
Configuration	Legacy keys (microsoft_*, ms_teams_* features)	Typed keys (microsoft_authentication.graph, short feature names)
Config migration	No dedicated migration command	Automatic migration at startup when legacy format is detected, with on-disk rewrite and .bak backup
State	JSON per tenant (state/state_<tenant>.json)	SQLite (state.db) with deduplication + outbox
Linux service	--enable_boot_start / --disable_boot_start	service enable-service / service disable-service
site_definition feature	Supported	Removed (ignored)

CLI Command Mapping

v1	Standalone
ms-teams-agent --version	ms-teams-agent --version
ms-teams-agent --config config.yaml	ms-teams-agent run --config config.yaml
ms-teams-agent --config config.yaml --call_id <ID>	ms-teams-agent run --config config.yaml --call-id <ID>
ms-teams-agent --config config.yaml --ignore_state	ms-teams-agent run --config config.yaml --ignore-state
(implicit at startup)	ms-teams-agent validate --config config.yaml
(no equivalent)	ms-teams-agent test-connection --config config.yaml
(no equivalent)	ms-teams-agent state show / reset / export
--enable_boot_start	service enable-service --config <path>
--disable_boot_start	service disable-service
--service_name_suffix=-prod	--instance prod
--force_service_creation	--force-service-creation

Configuration Key Mapping

Microsoft Authentication

v1 key	Standalone key
microsoft_authentication.microsoft_tenant_id	microsoft_authentication.graph.tenant_id
microsoft_authentication.microsoft_client_id	microsoft_authentication.graph.client_id
microsoft_authentication.microsoft_client_secret	microsoft_authentication.graph.client_secret
microsoft_authentication.microsoft_client_assertion_type	microsoft_authentication.graph.client_assertion_type
microsoft_authentication.microsoft_client_certificate_path	microsoft_authentication.graph.client_certificate_path
microsoft_authentication.microsoft_client_certificate_passphrase	microsoft_authentication.graph.client_certificate_passphrase
microsoft_authentication.microsoft_scope	microsoft_authentication.graph.scope
microsoft_authentication.microsoft_grant_type	microsoft_authentication.graph.grant_type
microsoft_authentication.microsoft_username	microsoft_authentication.vaac.username
microsoft_authentication.microsoft_password	microsoft_authentication.vaac.password

Collection, License and Logs

v1 key	Standalone key
collection_config.microsoft_max_call_duration_hours	collection_config.max_call_duration_hours
collection_config.logfile_log_level	collection_config.log_level
collection_config.license_file	license.filepath
collection_config.logging_services	Removed (ignored)

Features

v1 feature key	Standalone feature key
ms_teams_calls_collection	calls_collection
ms_teams_issues_collection	issues_collection
ms_teams_pstn_calls_collection	pstn_calls_collection
ms_teams_direct_routing_calls_collection	direct_routing_calls_collection
ms_teams_autoattendant_collection	autoattendant_collection
ms_teams_callqueue_collection	callqueue_collection
ms_teams_site_definition	Removed (ignored)

Minimal Standalone Configuration

microsoft_authentication:
  graph:
    tenant_id: "<tenant_id>"
    client_id: "<client_id>"
    client_secret: "<client_secret>"
    scope: "https://graph.microsoft.com/.default"
    grant_type: "client_credentials"
  vaac:
    username: "<vaac_username>"
    password: "<vaac_password>"

license:
  filepath: "/etc/ms-teams-observability-agent/license.json"

output:
  console:
    enabled: true

collection_config:
  max_call_duration_hours: 5
  interval_collection_minutes: 1
  log_level: "INFO"
  features:
    calls_collection:
      enabled: true
    issues_collection:
      enabled: false
    pstn_calls_collection:
      enabled: false
    direct_routing_calls_collection:
      enabled: false
    autoattendant_collection:
      enabled: false
    callqueue_collection:
      enabled: false

Note

Standalone accepts v1 legacy keys via an internal migrator, but this compatibility is transitional. Write Standalone keys directly for new deployments.

Configuration Migration Behavior

When the collector loads a legacy-format YAML config, Standalone automatically:

1. migrates keys to the current schema,
2. creates a backup file next to the original config (<config>.bak),
3. rewrites the migrated YAML to disk.

This auto-migration runs on startup when needed.

When to Use migrate-config vs Auto-Migration

• Use migrate-config when you want to migrate and review config files before runtime (for example in CI or change-management workflows).
• Rely on auto-migration when starting the collector normally and you are comfortable with startup-time migration.

State Migration

Standalone does not read the v1 JSON state (state/state_<tenant>.json) automatically at startup. You can still migrate v1 state manually with the temporary CLI command:

ms-teams-agent state migrate-v1 --source ./state-v1.json

See Temporary Migration Command for details and non-interactive flags.

If you prefer a clean cutover, starting with a clean state remains a valid path:

ms-teams-agent run --config ./config.yaml --ignore-state

Then run continuously:

ms-teams-agent run --config ./config.yaml

Recommended Cutover Procedure

1. Back up v1 config, license, state JSON, and any service scripts.
2. Create a config.yaml in Standalone format using the key mapping above.
3. Validate the config:

   ms-teams-agent validate --config ./config.yaml

4. Test Graph auth and exporters:

   ms-teams-agent test-connection --config ./config.yaml

5. Optional — dry run without exporting:

   ms-teams-agent run --config ./config.yaml --dry-run --ignore-state

6. Switch to production run or systemd service.

Linux Service Migration

v1	Standalone
sudo ms-teams-agent --config <path> --enable_boot_start	sudo ms-teams-agent service enable-service --config <path>
sudo ms-teams-agent --config <path> --disable_boot_start	sudo ms-teams-agent service disable-service
--service_name_suffix=-prod	--instance prod