Share via

EnrollmentGroup Class

  • Reference
Package:
com.microsoft.azure.sdk.iot.provisioning.service.configs
  • java.lang.Object
    • java.io.Serializable
      • 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"

}

</code></pre></p>



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\""

}

</code></pre></p>

Constructor Summary

Constructor Description
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\""

}

</code></pre></p>
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]"

            }

        }

    }

}

</code></pre></p>

Method Summary

Modifier and Type Method and Description
Attestation getAttestation()

Getter for the attestation mechanism.
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.
final void setAttestation(AttestationMechanism attestationMechanism)

Setter for the attestation.

Attestation mechanism is mandatory parameter that provides the mechanism type and the necessary keys/certificates
JsonElement toJsonElement()

Serializer

Creates aJsonElement  

</code> , which the content represents the information in this class and its subclasses in a JSON format.</p>

This is useful if the caller will integrate this JSON with jsons from other classes to generate a consolidated JSON.

Inherited Members

Serializable.toJson() Serializable.toString()

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\""

}

</code></pre></p>






						
Parameters:

							

								json
									- 
theString 

</code> with the JSON received from the provisioning service. </p>


							


						
Throws:

							

									IllegalArgumentException

									- If the provided JSON is null, empty, or invalid.

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]"

            }

        }

    }

}

</code></pre></p>






						
Parameters:

							

								enrollmentGroupId
									- 
theString 

</code> with an unique id for this enrollment group. </p>


							

							

								attestation
									- 
the Attestation mechanism that shall besignedCertificate 

</code> of <xref uid="com.microsoft.azure.sdk.iot.provisioning.service.configs.X509Attestation" data-throw-if-not-resolved="false" data-raw-source="X509Attestation"></xref> or<code>symmetricKey 

</code> of <xref uid="com.microsoft.azure.sdk.iot.provisioning.service.configs.SymmetricKeyAttestation" data-throw-if-not-resolved="false" data-raw-source="SymmetricKeyAttestation"></xref></p>


							


						
Throws:

							

									IllegalArgumentException

									- If one of the provided parameters is not correct.

Method Details

getAttestation

public Attestation getAttestation()

Getter for the attestation mechanism.

Returns:

TheAttestation  

</code> with the attestation content. It cannot be<code>null 

</code> . </p>

Throws:

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

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

Throws:

IllegalArgumentException -

If the provided attestation mechanism isnull  

</code> or invalid. </p>

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 -

theAttestationMechanism  

</code> with the new attestation mechanism. It can be `tpm`, `x509` or 'symmetricKey'. </p>

Throws:

IllegalArgumentException -

If the provided attestation mechanism isnull  

</code> . </p>

toJsonElement

public JsonElement toJsonElement()

Serializer

Creates aJsonElement  

</code> , which the content represents the information in this class and its subclasses in a JSON format.</p>

This is useful if the caller will integrate this JSON with jsons from other classes to generate a consolidated JSON.

Returns:

TheJsonElement  

</code> with the content of this class. </p>

Applies to