Migration

Introduction

The following endpoints can be used to automate the migration of 1.0 cloud nodes to the new 2.0 architecture.

Basic Endpoints

Perform a preflight check

This endpoint determines whether a 1.0 cloud node is ready to be migrated.

Request

GET https://accounts.pdk.io/api/migration/{{panel_id}}/preflight-check HTTP/1.1
Authorization: Bearer {{id_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
id_token	Header	String	Yes	A valid ID token.

Response

The example response below includes all warnings and errors that may be encountered. If the warnings and errors objects are empty, it is safe to proceed with the migration.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": false,
  "warnings": {
    "integrations": ["aad", "dw"]
  },
  "errors": {
    "softwareVersion": {
        "cnbackendVersion": "2.0.0",
        "saserverVersion": "2.0.0",
        "postgresVersion": "16.0",
        "mosquittoVersion": "2.0.11-5-2x"
    },
    "integrations": ["aad", "comelit"],
    "personalInfoMissing": true,
    "controllerOffline": [
        {
            "id": 123,
            "connection": 123,
            "wirelessAddress": "0013a20041e03be0",
            "description": "Test Connection"
        }
    ],
    "controllerVersion": [
        {
            "id": 123,
            "connection": 123,
            "wirelessAddress": "0013a20041e03be0",
            "description": "Test Connection",
            "firmwareVersion": "2.1.1",
            "stageFirmwareVersion": "2.1.2",
            "linkType": "ethernet",
            "updateRunning": true
        }
    ],
    "legacyDevice": [
        {
            "id": 123,
            "connection": 123,
            "wirelessAddress": "0013a20041e03be0",
            "description": "Test Device"
        }
    ],
    "invalidDevice": [
        {
            "id": 123,
            "connection": 123,
            "wirelessAddress": "0013a20041e03be0",
            "description": "Test Device",
            "propDelay": 3000
        }
    ]
  }
}

Initiate a migration

This endpoint performs a preflight check on a 1.0 cloud node and stages an equivalent 2.0 system. If the preflight check is successful, both systems become read-only until the migration is either completed or rolled back.

Request

POST https://accounts.pdk.io/api/migration/initiate HTTP/1.1
Authorization: Bearer {{id_token}}
Content-Type: application/json

{
  cloudNodeSN: "{{panel_id}}"
}

Parameter	Location	Type	Required	Description
id_token	Header	String	Yes	A valid ID token.
panel_id	Body	String	Yes	The cloud node serial number.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "1234ABC",
  "name": "Test Customer",
  "legacyOuId": "66a8fe3544c9d47e5f1d0ab9",
  "status": "Pending",
  "createdAt": "2024-07-30T15:12:53.015Z",
  "tasks": [
    {
      "taskId": "EXPORT_LEGACY_DATA",
      "status": "Pending"
    },
    {
      "taskId": "CREATE_CUSTOMER",
      "status": "Pending"
    },
    {
      "taskId": "CREATE_SYSTEM",
      "status": "Pending"
    },
    {
      "taskId": "TRANSFORM_SCHEMA",
      "status": "Pending"
    },
    {
      "taskId": "IMPORT_SYSTEM_DATA",
      "status": "Pending"
    },
    {
      "taskId": "ACTIVATE_SYSTEM",
      "status": "Pending"
    }
  ]
}

Retrieve the status of a migration

This endpoint provides details about the status of a migration. Note that the systemId property is not available until the IMPORT_SYSTEM_DATA task has a status of Completed.

Request

GET https://accounts.pdk.io/api/migration/{{panel_id}} HTTP/1.1
Authorization: Bearer {{id_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
id_token	Header	String	Yes	A valid ID token.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "1234ABC",
  "name": "Test Customer",
  "legacyOuId": "66a8fe3544c9d47e5f1d0ab9",
  "createdAt": "2024-07-30T15:12:53.015Z",
  "status": "Processing",
  "backupUrl": "s3://pdk_panel_backup/1234ABC/2024-08-26T18:41:50.714Z.tar.gz",
  "ouId": "66cccc9f08612a3811faf112",
  "systemId": "2e398b25-09c5-4bcd-9d0a-340e38f03ee7",
  "tasks": [
    {
      "taskId": "EXPORT_LEGACY_DATA",
      "status": "Completed",
      "startedAt": "2024-07-30T15:12:53.895Z",
      "updatedAt": "2024-07-30T15:12:53.895Z"
    },
    {
      "taskId": "CREATE_CUSTOMER",
      "status": "Processing",
      "startedAt": "2024-07-30T15:13:45.787Z",
      "updatedAt": "2024-07-30T15:13:45.891Z"
    },
    {
      "taskId": "CREATE_SYSTEM",
      "status": "Pending"
    },
    {
      "taskId": "TRANSFORM_SCHEMA",
      "status": "Pending"
    },
    {
      "taskId": "IMPORT_SYSTEM_DATA",
      "status": "Pending"
    },
    {
      "taskId": "ACTIVATE_SYSTEM",
      "status": "Pending"
    }
  ]
}

Complete a migration

This endpoint activates a staged 2.0 system and deletes the corresponding 1.0 system.

tip

Before completing a migration, be sure to store the newly created system ID, which is provided in the migration status object. This ID is needed to retrieve entity mappings after a migration is complete.

Request

POST https://accounts.pdk.io/api/migration/{{panel_id}}/complete HTTP/1.1
Authorization Bearer {{id_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
id_token	Header	String	Yes	A valid ID token.

Response

HTTP/1.1 204 No Content

Roll back a migration

This endpoint deletes a staged 2.0 system and removes the read-only restriction from the corresponding 1.0 system.

Request

POST https://accounts.pdk.io/api/migration/{{panel_id}}/rollback HTTP/1.1
Authorization Bearer {{id_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
id_token	Header	String	Yes	A valid ID token.

Response

HTTP/1.1 204 No Content

Retrieve entity mappings

Once a migration is complete, this endpoint can be used to retrieve mappings of 1.0 entities to their 2.0 counterparts.

Request

GET https://systems.pdk.io/api/{{system_id}}/id-mapping/{{cloud_node_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The ID of the newly migrated system.
cloud_node_id	Path	String	Yes	The ID of the newly migrated cloud node. This is the UUID assigned to the cloud node during migration (not the panel ID).
type	Path	Query	No	A comma-delimited list of entity types to be returned. Possible values include: cardFormat, connection, credential, device, floorGroup, group, holder, map, partition, report, and rule.
system_token	Header	String	Yes	A valid system token.

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "df32fb67-ceea-48fb-9307-2afe81bd3403",
    "legacyId": 2,
    "serialNumber": "1234ABC",
    "type": "connection",
    "systemId": "384cb63d-4334-4bd2-b7b6-e8be5b788cc7"
  },
  {
    "id": "ef74e6f7-450c-4e73-b56f-eb7e0ad51180",
    "legacyId": 36,
    "serialNumber": "1234ABC",
    "type": "cardFormat",
    "systemId": "384cb63d-4334-4bd2-b7b6-e8be5b788cc7"
  },
  {
    "id": "f0f274a2-b4fe-41fe-9c49-39e29dbed2b0",
    "legacyId": 7,
    "serialNumber": "1234ABC",
    "type": "holder",
    "systemId": "384cb63d-4334-4bd2-b7b6-e8be5b788cc7"
  },
  {
    "id": "5ac68a38-8f75-4f72-9612-b1e79fe2082f",
    "legacyId": 4,
    "serialNumber": "1234ABC",
    "type": "device",
    "systemId": "384cb63d-4334-4bd2-b7b6-e8be5b788cc7"
  },
  {
    "id": "1c71e159-b1e6-470b-b0c6-e21d8675e98e",
    "legacyId": 1,
    "serialNumber": "1234ABC",
    "type": "group",
    "systemId": "384cb63d-4334-4bd2-b7b6-e8be5b788cc7"
  },
  {
    "id": "7a022086-061a-434e-8de0-49e2339d5d6e",
    "legacyId": 0,
    "serialNumber": "1234ABC",
    "type": "partition",
    "systemId": "384cb63d-4334-4bd2-b7b6-e8be5b788cc7"
  },
  {
    "id": "ad7857ae-1f5a-4a8e-9699-f94db6701695",
    "legacyId": 2,
    "serialNumber": "1234ABC",
    "type": "rule",
    "systemId": "384cb63d-4334-4bd2-b7b6-e8be5b788cc7"
  }
]