Skip to main content

Installer Onboarding Integration

Erik Wihlborg
Updated

The purpose of this integration is to automate: 

  • Initial provisioning: Setting up an installer company (often a fleet) and a user administor, and grant the installer access to a fleet resource.
  • Ongoing administration: Adding additional installers and users, and grant or revoke installer´s access to fleet resources.

See the "Installer Onboarding Introduction" article for more information.

Initial provisioning

The initial provisioning serves to set up the requires resoruces in the SKF platform required to start commissioning devices. These resources are:

  • An installer company
  • A user administrator
  • An access rule that allowes the installer company access to a fleet resource

Provisioning mode

The API supports automated provisioning of installer companies based on a corporate email domain. This ensures global uniqueness within the platform and restricts which users can be created under a given company.

Installers that legitimately require a free email domain must use assisted provisioning. Assisted provisioning requires manual intervention and may introduce a delay.

Assisted provisioning can be requested using Initial Provisioning Option B (described below) or by contacting SKF Support.

Initial provisioning option A: Multiple requests

In this option, the TSP implements several requests to achieve the objective. Although this approach requires more effort, it gives the TSP more control over the onboarding experience, with the flexibility to adjust it as needed.

Note: Creating installers via POST /installers is only supported for companies associated with a corporate email domain (specified in allowedEmailDomain).

Step 1: Validate the supported provisioning mode (if you’re unsure)

GET /installers/provisioning-mode?domain=east-fleet.com

# Example response
{
  "domain": "east-fleet.com",
  "mode": "automated"
}

Step 2: Create an installer company

POST /installers

{
    "name": "East Fleet",
    "type": "fleet",
    "allowedEmailDomain": "east-fleet.com"
}

Step 3: Create a user

POST /installers/{installerId}/users

{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "firstName": "Joe",
    "lastName": "Doe",
    "email": "john.doe@east-fleet.com",
    "roles": [
        "user_admin"
    ]
}

Step 4: Grant the installer access to a fleet resource

PUT /installers/{installerId}/access/fleets/{fleetId}

Initial provisioning option B: A Single, comprehensive request

This option involves creating a single provisioning request that includes all the required information.

Note: This API operation supports setting up installers with corporate or free email domains

POST /installers/provisioning-requests

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "pending",
  "createdAt": "2019-08-24T14:15:22Z",
  "provisioningMode": "automated",
  "installer": {
    "name": "East Fleet",
    "type": "fleet",
    "allowedEmailDomain": "east-fleet.com"
  },
  "access": {
    "fleetId": "159032dc-e809-4a84-b5eb-15b4c0159138",
    "fleetName": "string"
  },
  "user": {
    "firstName": "Joe",
    "lastName": "Doe",
    "email": "john.doe@east-fleet.com",
    "roles": [
      "user_admin"
    ]
  }
}

Ongoing administration

Add a user to an existing installer

Step 1: Identify the installer ID for the company

GET /installers?domain=east-fleet.com

# Sample response:
{
  "installers": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  # <- this is the installer ID
      "name": "East Fleet",
      "allowedEmailDomains": [
        "east-fleet.com"
      ],
      "type": "fleet"
    }
  ]
}

Step 2: Add a user to the prevously identified installer

POST /installers/{installerId}/users

{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "firstName": "Joe",
    "lastName": "Doe",
    "email": "john.doe@east-fleet.com",
    "roles": [
        "user_admin"
    ]
}

Note: Access rules are processed every two hours; therefore, newly added users may require up to two hours before they are granted access.

Revoke an installer´s access to a fleet resource

DEL /installers/{installerId}/access/fleets/{fleetId}

View access rules

GET /installers/access

# Sample response
{
  "access": [
    {
      "installer": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "East Fleet"
      },
      "fleets": [
        {
          "id": "159032dc-e809-4a84-b5eb-15b4c0159138",
          "name": "Ken Trucks Inc.",
          "state": "pending",
          "createdAt": "2019-08-24T14:15:22Z"
        }
      ]
    }
  ]
}