ProvisionEntities

ProvisionEntities is used to add a device. One device is added for each input item. If the specified user, user group, or company does not exist, it will be added. The equivalent option in the dashboard is the Add device button on the Company or Devices page.

Signature

ServiceResponse ProvisionEntities (CallingContext callingContext, ProvisionEntitiesInput input, out ProvisionEntitiesResult result);

Data structure

The input to ProvisionEntities is an array of ProvisionEntitiesInput structures which contain the information on the device to be added.

[DataContract]
public class ProvisionEntitiesInput
{
    public ProvisionEntitiesInput()
    {
    }

    [DataMember]
    public bool HaltOnProvisioningError;

    [DataMember]
    public bool ProceedOnValidationError;

    [DataMember]
    public bool ValidateOnly;

    [DataMember]
    public Guid PartnerId;

    [DataMember]
    public ProvisionElement[] ProvisionElements; 
}

• HaltOnProvisioningError—When true, the method will stop after the first provisioning error. When false, the method will continue after the first provisioning error.
• ProceedOnValidationError—When true, the method will continue with provisioning even if initial validation fails. When false, the method will stop if initial validation fails.
• ValidateOnly—When true, only validation will be performed. No provisioning will be performed. When false, both validation and provisioning will be performed.
• PartnerId—Specify the ID of the partner the device should be assigned to. If you do not specify a partner ID, the partner ID associated with the CallingContext user will be used.
• ProvisionElements—Specify the elements for the device to be added.

[DataContract]
public class ProvisionElement
{
    [DataMember]
    public int Id;

    [DataMember]
    public ProvisioningStatus Status;

    [DataMember]
    public string Info;

    [DataMember]
    public EntityState UserState;

    [DataMember]
    public string Email;

    [DataMember]
    public string FirstName;

    [DataMember]
    public string LastName;

    [DataMember]
    public string UserCustom1;        

    [DataMember]
    public string UserCustom2;
        
    [DataMember]
    public string UserCustom3;        

    [DataMember]
    public EntityState UserGroupState;

    [DataMember]
    public string UserGroup;        

    [DataMember]
    public EntityState CompanyState;

    [DataMember]
    public string CompanyName;        

    [DataMember]
    public EntityState DeviceState;

    [DataMember]
    public string DeviceName;        

    [DataMember]
    public string DeviceId;        

    [DataMember]
    public string PolicyName;        

    [DataMember]
    public int CurrentStorageGB;

    [DataMember]
    public string DeviceCustom1;        

    [DataMember]
    public string DeviceCustom2;
        
    [DataMember]
    public string DeviceCustom3;

    [DataMember]
    public bool SendActivationEmail;

    [DataMember]
    public string ActivationCode;
}

• Id—Do not use this field. It is used for the row number when bulk importing using Microsoft Excel.
• Status—Do not use this field. It is an output property that identifies the status of the new device.
• Info—Do not use this field. It is an output property that identifies the comments for the new device.
• UserState—Do not use this field. It is an output property that identifies the status of the new or modified user.
• * Email—Specify the email address of the user associated with the device. If the email address does not exist, the user will be added. If the email address already exists, the associated user will be used. This property is required.
• FirstName—Specify the first name of the user. Pass null if you do not want to change the field. An empty string will leave the field blank.
• LastName—Specify the last name of the user. Pass null if you do not want to change the field. An empty string will leave the field blank.
• Custom—Optionally, specify any of the three properties for storing custom strings for the user. Pass null if you do not want to change the field. An empty string will leave the field blank.
• UserGroupState—Do not use this field. It is an output property that identifies if the user group already exists.
• * UserGroup—Specify the user group the device should be assigned to. This property is required, however, an empty string will assign the device to the All Uses group.
• CompanyState—Do not use this field. It is an output property that identifies if the company already exists.
• * CompanyName—Specify the company the device should be assigned to. This property is required, however, an empty string will assign the device to the Unknown company.
• DeviceState—Do not use this field. It is an output property that identifies if the device already exists.
• DeviceName—Specify the name of the device. An empty string will assign an automatically generated name.
• * DeviceId—Specify Guid.Empty.ToString() to add a new device, and the new device ID will be returned. Specify the same or a new ID to update an existing device. This property is required.
• * PolicyName—Specify the name of the policy set to use. The string must match exactly. This property is required.
• * CurrentStorageGB—Specify the quota limit, in GB, for the device. The limit must be less than or equal to the maximum limit defined in the specified policy set. This property is required when adding a new device.
• DeviceCustom—Optionally, specify any of the three properties for storing custom strings for the device. Pass null if you do not want to change the field. An empty string will leave the field blank.
• * SendActivationEmail—When true, an activation message will be sent to the specified email address. When false, the activation email will not be sent.
• ActivationCode—Do not use this field. It is an output property that identifies the activation code for the device.

* These properties are required.

Result

In addition to the BaseServiceResult described in General API structure, ProvisionEntitiesResult is an array of ProvisionElements as described above.

[DataContract]
public class ProvisionEntitiesResult : BaseServiceResult
{
    public ProvisionElements[] Element;
    {
    }
}