EnrollmentGroup Class

Reference

Package:: com.microsoft.azure.sdk.iot.provisioning.service.configs

Maven Artifact:: com.microsoft.azure.sdk.iot.provisioning:provisioning-service-client:1.7.0

java.lang.Object
- com.microsoft.azure.sdk.iot.provisioning.service.configs.Serializable
- - com.microsoft.azure.sdk.iot.provisioning.service.configs.EnrollmentGroup

public class EnrollmentGroup
extends Serializable

Representation of a single Device Provisioning Service enrollment group with a JSON serializer and deserializer.

This object is used to send EnrollmentGroup information to the provisioning service, or receive EnrollmentGroup information from the provisioning service.

To create or update an EnrollmentGroup on the provisioning service you should fill this object and call the public API createOrUpdateEnrollmentGroup(EnrollmentGroup enrollmentGroup). The minimum information required by the provisioning service is the #enrollmentGroupId and the #attestation.

To provision a device using EnrollmentGroup, it must contain a X509 chip with a signingCertificate for the X509Attestation mechanism, or use SymmetricKeyAttestation mechanism.

The content of this class will be serialized in a JSON format and sent as a body of the rest API to the provisioning service.

When serialized, an EnrollmentGroup will look like the following example:

{
     "enrollmentGroupId":"validEnrollmentGroupId",
     "attestation":{
         "type":"x509",
         "signingCertificates":{
             "primary":{
                 "certificate":"[valid certificate]"
             }
         }
     },
     "iotHubHostName":"ContosoIoTHub.azure-devices.net",
     "provisioningStatus":"enabled"
 }

The content of this class can be filled by a JSON, received from the provisioning service, as result of a EnrollmentGroup operation like create, update, or query EnrollmentGroup.

The following JSON is a sample of the EnrollmentGroup response, received from the provisioning service.

{
     "enrollmentGroupId":"validEnrollmentGroupId",
     "attestation":{
         "type":"x509",
         "signingCertificates":{
             "primary":{
                 "certificate":"[valid certificate]",
                 "info": {
                     "subjectName": "CN=ROOT_00000000-0000-0000-0000-000000000000, OU=Azure IoT, O=MSFT, C=US",
                     "sha1Thumbprint": "0000000000000000000000000000000000",
                     "sha256Thumbprint": "validEnrollmentGroupId",
                     "issuerName": "CN=ROOT_00000000-0000-0000-0000-000000000000, OU=Azure IoT, O=MSFT, C=US",
                     "notBeforeUtc": "2017-11-14T12:34:18Z",
                     "notAfterUtc": "2017-11-20T12:34:18Z",
                     "serialNumber": "000000000000000000",
                     "version": 3
                 }
             }
         }
     },
     "iotHubHostName":"ContosoIoTHub.azure-devices.net",
     "provisioningStatus":"enabled",
     "createdDateTimeUtc": "2017-09-28T16:29:42.3447817Z",
     "lastUpdatedDateTimeUtc": "2017-09-28T16:29:42.3447817Z",
     "etag": "\"00000000-0000-0000-0000-00000000000\""
 }

Constructor Summary

Constructor	Description
EnrollmentGroup(String json)	CONSTRUCTOR
EnrollmentGroup(String enrollmentGroupId, Attestation attestation)	CONSTRUCTOR

Method Summary

Modifier and Type	Method and Description
AllocationPolicy	getAllocationPolicy() Getter for the allocation policy.
Attestation	getAttestation() Getter for the attestation mechanism.
DeviceCapabilities	getCapabilities()
java.util.Date	getCreatedDateTimeUtc() Getter for the createdDateTimeUtcDate.
CustomAllocationDefinition	getCustomAllocationDefinition() Getter for the custom allocation definition policy.
java.lang.String	getEnrollmentGroupId() Getter for the enrollmentGroupId.
java.lang.String	getEtag() Getter for the etag.
TwinState	getInitialTwin() Getter for the initialTwin.
java.lang.String	getIotHubHostName() Getter for the iotHubHostName.
java.util.Collection<java.lang.String>	getIotHubs() Getter for the list of IoTHub names that the device can be allocated to..
java.util.Date	getLastUpdatedDateTimeUtc() Getter for the lastUpdatedDateTimeUtcDate.
ProvisioningStatus	getProvisioningStatus() Getter for the provisioningStatus.
ReprovisionPolicy	getReprovisionPolicy() Getter for the reprovision policy.
void	setAllocationPolicy(AllocationPolicy allocationPolicy) Setter for the allocation policy.
void	setAttestation(Attestation attestation) Setter for the attestation.
protected final void	setAttestation(AttestationMechanism attestationMechanism) Setter for the attestation.
final void	setCapabilities(DeviceCapabilities capabilities)
protected final void	setCreatedDateTimeUtc(String createdDateTimeUtc) Setter for the createdDateTimeUtc.
void	setCustomAllocationDefinition(CustomAllocationDefinition customAllocationDefinition) Setter for the custom allocation definition policy.
protected final void	setEnrollmentGroupId(String enrollmentGroupId) Setter for the enrollmentGroupId.
void	setEtag(String etag) Deprecated as of provisioning-service-client version 1.3.3, please use setEtagFinal(String etag) Setter for the etag.
final void	setEtagFinal(String etag) Setter for the etag.
void	setInitialTwin(TwinState initialTwin) Setter for the initialTwin.
final void	setInitialTwinFinal(TwinState initialTwin) Setter for the initialTwin.
void	setIotHubHostName(String iotHubHostName) Setter for the iotHubHostName.
final void	setIotHubHostNameFinal(String iotHubHostName) Setter for the iotHubHostName.
void	setIotHubs(Collection<String> iotHubs) Setter for the list of IotHubs available for allocation.
protected final void	setLastUpdatedDateTimeUtc(String lastUpdatedDateTimeUtc) Setter for the lastUpdatedDateTimeUtc.
void	setProvisioningStatus(ProvisioningStatus provisioningStatus) Deprecated as of provisioning-service-client version 1.3.3, please use setProvisioningStatusFinal(ProvisioningStatus provisioningStatus) Setter for the provisioningStatus.
final void	setProvisioningStatusFinal(ProvisioningStatus provisioningStatus) Setter for the provisioningStatus.
void	setReprovisionPolicy(ReprovisionPolicy reprovisionPolicy) Setter for the reprovision policy.
com.google.gson.JsonElement	toJsonElement() Serializer

Methods inherited from Serializable

toJson toJsonElement toString

Methods inherited from java.lang.Object

java.lang.Object.clone java.lang.Object.equals java.lang.Object.finalize java.lang.Object.getClass java.lang.Object.hashCode java.lang.Object.notify java.lang.Object.notifyAll java.lang.Object.wait java.lang.Object.wait java.lang.Object.wait

Constructor Details

EnrollmentGroup

public EnrollmentGroup(String json)

CONSTRUCTOR

This constructor creates an instance of the enrollment group filling the class with the information provided in the JSON.

The following JSON is a sample of the EnrollmentGroup response, received from the provisioning service.

{
     "enrollmentGroupId":"validEnrollmentGroupId",
     "attestation":{
         "type":"x509",
         "signingCertificates":{
             "primary":{
                 "certificate":"[valid certificate]",
                 "info": {
                     "subjectName": "CN=ROOT_00000000-0000-0000-0000-000000000000, OU=Azure IoT, O=MSFT, C=US",
                     "sha1Thumbprint": "0000000000000000000000000000000000",
                     "sha256Thumbprint": "validEnrollmentGroupId",
                     "issuerName": "CN=ROOT_00000000-0000-0000-0000-000000000000, OU=Azure IoT, O=MSFT, C=US",
                     "notBeforeUtc": "2017-11-14T12:34:18Z",
                     "notAfterUtc": "2017-11-20T12:34:18Z",
                     "serialNumber": "000000000000000000",
                     "version": 3
                 }
             }
         }
     },
     "iotHubHostName":"ContosoIoTHub.azure-devices.net",
     "provisioningStatus":"enabled"
     "createdDateTimeUtc": "2017-09-28T16:29:42.3447817Z",
     "lastUpdatedDateTimeUtc": "2017-09-28T16:29:42.3447817Z",
     "etag": "\"00000000-0000-0000-0000-00000000000\""
 }

Parameters:

json - the String with the JSON received from the provisioning service.

EnrollmentGroup

public EnrollmentGroup(String enrollmentGroupId, Attestation attestation)

CONSTRUCTOR

This constructor creates an instance of the enrollment group with the minimum set of information required by the provisioning service.

When serialized, an EnrollmentGroup will look like the following example:

{
     "enrollmentGroupId":"validEnrollmentGroupId",
     "attestation":{
         "type":"x509",
         "signingCertificates":{
             "primary":{
                 "certificate":"[valid certificate]"
             }
         }
     }
 }

Parameters:

enrollmentGroupId - the String with an unique id for this enrollment group.

attestation - the Attestation mechanism that shall be signedCertificate of X509Attestation or symmetricKey of SymmetricKeyAttestation

Method Details

getAllocationPolicy

public AllocationPolicy getAllocationPolicy()

Getter for the allocation policy.

Returns:

The AllocationPolicy with the allocationPolicy content.

getAttestation

public Attestation getAttestation()

Getter for the attestation mechanism.

Returns:

The Attestation with the attestation content. It cannot be null.

Throws:

ProvisioningServiceClientException - If the type of the attestation mechanism is unknown.

getCapabilities

public DeviceCapabilities getCapabilities()

getCreatedDateTimeUtc

public Date getCreatedDateTimeUtc()

Getter for the createdDateTimeUtcDate.

Returns:

The Date with the createdDateTimeUtcDate content. It can be null.

getCustomAllocationDefinition

public CustomAllocationDefinition getCustomAllocationDefinition()

Getter for the custom allocation definition policy.

Returns:

The CustomAllocationDefinition policy.

getEnrollmentGroupId

public String getEnrollmentGroupId()

Getter for the enrollmentGroupId.

Returns:

The String with the enrollmentGroupId content. It cannot be null or empty.

getEtag

public String getEtag()

Getter for the etag.

Returns:

The String with the etag content. It can be null.

getInitialTwin

public TwinState getInitialTwin()

Getter for the initialTwin.

Returns:

The TwinState with the initialTwin content. Its optional and can be null.

getIotHubHostName

public String getIotHubHostName()

Getter for the iotHubHostName.

Returns:

The String with the iotHubHostName content. It cannot be null or empty.

getIotHubs

public Collection getIotHubs()

Getter for the list of IoTHub names that the device can be allocated to..

Returns:

The AllocationPolicy with the allocationPolicy content.

getLastUpdatedDateTimeUtc

public Date getLastUpdatedDateTimeUtc()

Getter for the lastUpdatedDateTimeUtcDate.

Returns:

The Date with the lastUpdatedDateTimeUtcDate content. It can be null.

getProvisioningStatus

public ProvisioningStatus getProvisioningStatus()

Getter for the provisioningStatus.

Returns:

The ProvisioningStatus with the provisioningStatus content. It can be 'enabled' or 'disabled'.

getReprovisionPolicy

public ReprovisionPolicy getReprovisionPolicy()

Getter for the reprovision policy.

Returns:

The ReprovisionPolicy with the reprovisionPolicy content.

setAllocationPolicy

public void setAllocationPolicy(AllocationPolicy allocationPolicy)

Setter for the allocation policy.

Parameters:

allocationPolicy - the AllocationPolicy with the allocation policy of this resource. Overrides the tenant level allocation policy.

setAttestation

public void setAttestation(Attestation attestation)

Setter for the attestation.

Attestation mechanism is mandatory parameter that provides the mechanism type and the necessary certificates.

EnrollmentGroup only accept X509Attestation with the RootCertificates, or SymmetricKeyAttestation with Primary and Secondary Keys. You can create an X509Attestation by providing the .pem content to createFromRootCertificates(String primary, String secondary). You can create a SymmetricKeyAttestation by providing the Primary and Secondary Keys in Base64 format.

Parameters:

attestation - the Attestation with the new attestation mechanism. It shall be X509Attestation or SymmetricKeyAttestation

setAttestation

protected final void setAttestation(AttestationMechanism attestationMechanism)

Setter for the attestation.

Attestation mechanism is mandatory parameter that provides the mechanism type and the necessary keys/certificates

Parameters:

attestationMechanism - the AttestationMechanism with the new attestation mechanism. It can be tpm, x509 or 'symmetricKey'.

setCapabilities

public final void setCapabilities(DeviceCapabilities capabilities)

Parameters:

capabilities - the device capabilities to set

setCreatedDateTimeUtc

protected final void setCreatedDateTimeUtc(String createdDateTimeUtc)

Setter for the createdDateTimeUtc.

This Date and Time is provided by the provisioning service. If the enrollmentGroup is not created yet, this string can represent an invalid Date. In this case, it will be ignored. Example of the expected format: "2016-06-01T21:22:43.7996883Z"

Parameters:

createdDateTimeUtc - the String with the new createdDateTimeUtc. It can be null, empty or not valid.

setCustomAllocationDefinition

public void setCustomAllocationDefinition(CustomAllocationDefinition customAllocationDefinition)

Setter for the custom allocation definition policy.

Parameters:

customAllocationDefinition - the CustomAllocationDefinition with the custom allocation policy of this resource.

setEnrollmentGroupId

protected final void setEnrollmentGroupId(String enrollmentGroupId)

Setter for the enrollmentGroupId.

A valid enrollment group Id shall follow this criteria. A case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.

Parameters:

enrollmentGroupId - the String with the new enrollmentGroupId. It cannot be null, empty, or invalid.

setEtag

public void setEtag(String etag)

Deprecated

as of provisioning-service-client version 1.3.3, please use setEtagFinal(String etag)

Setter for the etag.

Parameters:

etag - the String with the new etag. It cannot be null, empty or invalid.

setEtagFinal

public final void setEtagFinal(String etag)

Setter for the etag.

Parameters:

etag - the String with the new etag. It cannot be null, empty or invalid.

setInitialTwin

public void setInitialTwin(TwinState initialTwin)

Setter for the initialTwin.

It provides a Twin precondition for the provisioned device.

Parameters:

initialTwin - the TwinState with the new initialTwin. It cannot be null.

setInitialTwinFinal

public final void setInitialTwinFinal(TwinState initialTwin)

Setter for the initialTwin.

It provides a Twin precondition for the provisioned device.

Parameters:

initialTwin - the TwinState with the new initialTwin. It cannot be null.

setIotHubHostName

public void setIotHubHostName(String iotHubHostName)

Setter for the iotHubHostName.

A valid iothub host name shall follow this criteria. A case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. A valid host name shall have, at least 2 parts separated by '.'.

Parameters:

iotHubHostName - the String with the new iotHubHostName. It cannot be null, empty, or invalid.

setIotHubHostNameFinal

public final void setIotHubHostNameFinal(String iotHubHostName)

Setter for the iotHubHostName.

Parameters:

iotHubHostName - the String with the new iotHubHostName. It cannot be null, empty, or invalid.

setIotHubs

public void setIotHubs(Collection iotHubs)

Setter for the list of IotHubs available for allocation.

Parameters:

iotHubs - the List of names of IoT hubs the device(s) in this resource can be allocated to. Must be a subset of tenant level list of IoT hubs

setLastUpdatedDateTimeUtc

protected final void setLastUpdatedDateTimeUtc(String lastUpdatedDateTimeUtc)

Setter for the lastUpdatedDateTimeUtc.

Parameters:

lastUpdatedDateTimeUtc - the String with the new lastUpdatedDateTimeUtc. It can be null, empty or not valid.

setProvisioningStatus

public void setProvisioningStatus(ProvisioningStatus provisioningStatus)

Deprecated

as of provisioning-service-client version 1.3.3, please use setProvisioningStatusFinal(ProvisioningStatus provisioningStatus)

Setter for the provisioningStatus.

It provides a Status precondition for the provisioned device.

Parameters:

provisioningStatus - the ProvisioningStatus with the new provisioningStatus. It cannot be null.

setProvisioningStatusFinal

public final void setProvisioningStatusFinal(ProvisioningStatus provisioningStatus)

Setter for the provisioningStatus.

It provides a Status precondition for the provisioned device.

Parameters:

provisioningStatus - the ProvisioningStatus with the new provisioningStatus. It cannot be null.

setReprovisionPolicy

public void setReprovisionPolicy(ReprovisionPolicy reprovisionPolicy)

Setter for the reprovision policy.

Parameters:

reprovisionPolicy - the ReprovisionPolicy with the behavior when a device is re-provisioned to an IoT hub.

toJsonElement

public JsonElement toJsonElement()

Serializer

Creates a JsonElement, which the content represents the information in this class and its subclasses in a JSON format. This is useful if the caller will integrate this JSON with jsons from other classes to generate a consolidated JSON.

Overrides:

EnrollmentGroup.toJsonElement()

Returns:

The JsonElement with the content of this class.

Share via

EnrollmentGroup Class

Constructor Summary

Method Summary

Methods inherited from Serializable

Methods inherited from java.lang.Object

Constructor Details

EnrollmentGroup

EnrollmentGroup

Method Details

getAllocationPolicy

getAttestation

getCapabilities

getCreatedDateTimeUtc

getCustomAllocationDefinition

getEnrollmentGroupId

getEtag

getInitialTwin

getIotHubHostName

getIotHubs

getLastUpdatedDateTimeUtc

getProvisioningStatus

getReprovisionPolicy

setAllocationPolicy

setAttestation

setAttestation

setCapabilities

setCreatedDateTimeUtc

setCustomAllocationDefinition

setEnrollmentGroupId

setEtag

setEtagFinal

setInitialTwin

setInitialTwinFinal

setIotHubHostName

setIotHubHostNameFinal

setIotHubs

setLastUpdatedDateTimeUtc

setProvisioningStatus

setProvisioningStatusFinal

setReprovisionPolicy

toJsonElement

Applies to

Additional resources