User

The SDK allows for the host application to retrieve or update user information.

Activation

A user is considered valid if all the following criterias are fulfilled:

• Created

• Activated

• Not deactivated

The SDK does not verify the status of a user per se, but will report request failures if the user is not in an acceptable state. For example, an unactivated user could collect data (trips), but would not be able to submit those trips, or retrieve any information from the DriveSync server.

Activating while enrolling

Users can be activated via the enrollment file (refer to the enrollment documentation and example provided by the support team). This part will not be covered here, as it relies on the usage of an external XML/CSV file. As a quick summary, the XML/CSV file allows for a user to be created (enrolled) and activated at the same time.

Activating a user via the SDK

This feature allows for an existing user to be activated. In order to do so, the user needs to submit some information which will allow DriveSync to verify that the user is the correct one, and link that user to a specific ID (similar to the Enterprise external Id in the XML/CSV file for enrollment).

Required information

• Activation ID: This must match the activation ID provided during the user enrollment. This value must be unique, and could be considered as some sort of Username.

• Activation Code: This value is generated by DriveSync, and sent to the user via email (the email address must provided during the enrollment). This information should be known only by your user and can be considered as a one-use security token. This value is valid for one activation only, and does expire after a set period of time.

• Email address: This value must match the email address provided during the user enrollment.

• External user Id / JWT SUB: This value is used by DriveSync to match a user from the host application, to a user on the DriveSync server. This is essentially the same information as the "enterprise reference ID" when the activation is done during the enrollment. This value must match the Identity#externalReferenceID value afterward.

Concrete example

Enrolled via XML, activated via SDK

TLDR: When activating, make sure that the current Identity corresponds to the user you want to activate. The identity will be used to link your user, to the DriveSync user being activated. In the XML file sent to DriveSync, the following fields were provided:

• enterprise_id: ent_123

• activation_id: act_123

• enterprise_reference_id: placeholder_value

• email_address: [e-mail]

• etc....

The enterprise_reference_id in this scenario is a placeholder value, as it is not necessarily known during the enrollment. Note that if you were to enroll and activate at the same time, the enterprise_reference_id value must be set to the actual value.

When activating, the SDK will link the user corresponding to the current Identity#externalReferenceID to the DriveSync user (when activating via the file, this is done automatically, based on the enterprise_reference_id).

To activate a user, the following API can be used.

Swift

let service = ActivationService()
service.activate(activationId: activationId,
                 activationCode: activationCode,
                 emailAddress: emailAddress then: { result in
    switch result {
    case .sucess(_):
        // activation successful
    case .failure(_):
        // error
    }
})

Kotlin

val service = ActivationService()
service.activate(activationId,
                 activationCode,
                 emailAddress, 
      if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val user = result.value
        completionHandler(user)
    }
}

Fetch user information

Parameters:

expansions: The expansions applied for a user

Expansions options are below:

• ASSOCIATEDUSERS

• SHAREDINFORMATION

• ASSOCIATEDACCOUNT

• CUSTOMFIELDS

• ROLE

To fetch user information, the following API can be used.

Swift

let userService = UserService()
userService.fetch(then: { result in 
	if let user = result.value {
		// Success
		completionHandler(user)
	} else {
		// failure
	}
})

Kotlin

val userService = UserService()
userService.fetch { result: Result<User?> ->
    if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val user = result.value
        completionHandler(user)
    }
}

Update user information

The HostApp can update the user information upon success.

Concrete example

To update user information, the following API can be used.

Swift

let userService = UserService()
userService.update(displayName: displayName,
                   postalCode: postalCode,
                   gender: gender,
                   dateOfBirth: dateOfBirth, then: { result in
    switch result {
    case .sucess(_):
        // update successful
    case .failure(_):
        // error
    }
})