Name	Name	Last commit message	Last commit date
parent directory ..
src/main	src/main
pom.xml	pom.xml
readme.md	readme.md

Provisioning Service Client Sample For EnrollmentGroup

Overview

This is a quick tutorial with the steps to create, get, query, and delete an EnrollmentGroup in the Microsoft Azure IoT Hub Device Provisioning Service using the Provisioning Service Client on the java SDK.

All the artifacts that you need to execute this sample are ready to be built and executed on this sample.

References

Provisioning service client documentation Provisioning service client source code

How to run the samples on Linux or Windows

Note that the samples for Windows and Linux use Maven.

Clone the java SDK repo (https://github.com/Azure/azure-iot-sdk-java.git).
Compile the SDK. This step is only necessary if you don't want to use a precompiled Maven package.
1. Change to the root azure-iot-sdk-java directory.
2. Run mvn install. It will download all needed packages, compile and test the SDK.
3. At the end of this step, you will have the com.microsoft.azure.sdk.iot.provisioning.service on your machine.
Navigate to the sample root azure-iot-sdk-java/provisioning/provisioning-samples/service-enrollment-group-sample.

Edit the /src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceEnrollmentGroupSample.java to add your provisioning service information, you must edit:

Replace the [Provisioning Connection String] by the Provisioning Connection String that you copied from the portal.

/*
 * Details of the Provisioning.
 */
private static final String PROVISIONING_CONNECTION_STRING = "[Provisioning Connection String]";

You must copy the root certificate for the group of devices. If you don't have it, you can use the provisioning X509 cert generator. Fill the PUBLIC_KEY_CERTIFICATE_STRING with the root certificate. Be careful to do not change your certificate, adding or removing characters like spaces, tabs or new lines (\n).

private static final String PUBLIC_KEY_CERTIFICATE_STRING =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

Optionally, fill the IOTHUB_HOST_NAME with the Iot Hub that you linked to your provisioning service.

private static final String IOTHUB_HOST_NAME = "[Host name].azure-devices.net";

Note: If you will not provide these parameters, you must remove the lines #62 and #63, which add it to the enrollmentGroup configuration, from your sample.

enrollmentGroup.setIotHubHostName(IOTHUB_HOST_NAME);                // Optional parameter.
enrollmentGroup.setProvisioningStatus(ProvisioningStatus.ENABLED);  // Optional parameter.

In a command line, navigate to the directory azure-iot-sdk-java/provisioning/provisioning-samples/service-enrollment-group-sample where the pom.xml file for this test lives, and build your sample:
```
{sample root}/>mvn install -DskipTests
```
Navigate to the folder containing the executable JAR file for the sample and run the sample as follows:

The executable JAR file for create an enrollmentGroup can be found at:
```
{sample root}/target/service-enrollment-group-sample-{version}-with-deps.jar
```
Navigate to the target directory that containing the jar. Run the sample using the following command:
```
java -jar ./service-enrollment-group-sample-{version}-with-deps.jar
```

How to create a new provisioning App, step by step

If you prefer to create and populate your own java app, this section will guide you step by step.

If you don't want to use the precompiled Service SDK, follow the steps 1 and 2 above to produce it locally on your machine.
On your development machine, create a empty folder called provisioning-getstarted. That will be the base directory for all provisioning samples that you want to create.
Navigate to the provisioning-getstarted folder, create a Maven project called service-enrollment-group-sample, using the following command at your command prompt. Note this is a single, long command:

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=service-enrollment-group-sample -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

At your command prompt, navigate to the service-enrollment-group-sample folder.
Using a text editor, open the pom.xml file in the service-enrollment-group-sample folder and add the following dependency to the dependencies node. This dependency enables you to use the provisioning-service-client package in your app to communicate with your Device Provisioning Service:
```
<dependencies>
    <dependency>
        <groupId>com.microsoft.azure.sdk.iot.provisioning</groupId>
        <artifactId>provisioning-service-client</artifactId>
        <version>0.0.1</version>
    </dependency>
</dependencies>
```

Add the following build node after the dependencies node. This configuration (1) instructs Maven to use java 1.8 to build the app, (2) create a manifest to point the main entrance of your sample to the App class in the App.java, and (3) create a full contained jar, including dependencies:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <version>2.6</version>
            <configuration>
                <archive>
                    <manifest>
                        <addClasspath>true</addClasspath>
                        <mainClass>com.mycompany.app.App</mainClass>
                    </manifest>
                </archive>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.3</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
        </plugin>
        <plugin>
            <artifactId>maven-shade-plugin</artifactId>
            <version>2.4</version>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                    <configuration>
                        <filters>
                            <filter>
                                <artifact>*:*</artifact>
                                <excludes>
                                    <exclude>META-INF/*.SF</exclude>
                                    <exclude>META-INF/*.RSA</exclude>
                                </excludes>
                            </filter>
                        </filters>
                        <shadedArtifactAttached>true</shadedArtifactAttached>
                        <shadedClassifierName>with-deps</shadedClassifierName>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Save and close the pom.xml file.
At this point you can build and run your new App to make sure that everything is working as expected.
1. In a command line, navigate to the sample folder (where the pom.xml file lives) and build it:
```
{sample root}/>mvn install
```
1. Navigate to the directory service-enrollment-group-sample\target containing the .jar file.
2. Run the sample using the following command:
```
java -jar ./service-enrollment-group-sample-1.0-SNAPSHOT-with-deps.jar
```
1. As a result, it should print Hello world! in the screen.
Now, you are ready to write the provisioning code to create the enrollmentGroup. Using a text editor, open the service-enrollment-group-sample\src\main\java\com\mycompany\app\App.java file.

Add the following import statements at the beginning of the file, after the package com.mycompany.app;:

import com.microsoft.azure.sdk.iot.provisioning.service.ProvisioningServiceClient;
import com.microsoft.azure.sdk.iot.provisioning.service.Query;
import com.microsoft.azure.sdk.iot.provisioning.service.configs.*;
import com.microsoft.azure.sdk.iot.provisioning.service.exceptions.ProvisioningServiceClientException;

import java.util.UUID;

Copy the connection string for your Device Provisioning Service from the portal, you will need it for the next step.
1. Access the Azure portal.
2. Navigate to your Device Provisioning Service.
3. Click on Shared access policies.
4. Select the desired POLICY. It should be the one that you have EnrollmentWrite permission.
5. Copy the Primary key connection string.

Add the following class-level variables to the App class. Replace the {Provisioning Connection String} with your provisioning connection string:

/*
 * Details of the Provisioning.
 */
private static final String PROVISIONING_CONNECTION_STRING = "{Provisioning Connection String}";

You must copy the root certificate for the group of devices. If you don't have it, you can use the provisioning X509 cert generator. Add the follow class-level variable to the App, and fill the PUBLIC_KEY_CERTIFICATE_STRING with the root certificate.

private static final String PUBLIC_KEY_CERTIFICATE_STRING =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

Update your main method signature to include the following throws clause:

public static void main(String[] args) throws ProvisioningServiceClientException

Create a new instance of the ProvisioningServiceClient replacing the System.out.println( "Hello World!" ); by:

 System.out.println("Beginning my sample for the Provisioning Service Client!");

 // ********************************** Create a Provisioning Service Client ************************************
 ProvisioningServiceClient provisioningServiceClient =
         ProvisioningServiceClient.createFromConnectionString(PROVISIONING_CONNECTION_STRING);

After that, you can create a new enrollmentGroup.

Every enrollmentGroup needs a unique name, called EnrollmentGroupId, and an Attestation that must be a root certificate on X509Attestation.

Once you defined the EnrollmentGroupId and the Attestation mechanism, you can create the EnrollmentGroup configuration. Other optional parameters can be added, for instance, the IotHubHostName, and the ProvisioningStatus.

// *************************************** Create a new enrollmentGroup ****************************************
System.out.println("\nCreate a new enrollmentGroup...");

String enrollmentGroupId = "enrollmentgroupid-" + UUID.randomUUID();
Attestation attestation = X509Attestation.createFromRootCertificates(PUBLIC_KEY_CERTIFICATE_STRING);

EnrollmentGroup enrollmentGroup =
        new EnrollmentGroup(
                enrollmentGroupId,
                attestation);
enrollmentGroup.setIotHubHostName("[Host name].azure-devices.net");    // Optional, remove if you don't need. Must fit the linked IoT Hub.
enrollmentGroup.setProvisioningStatus(ProvisioningStatus.ENABLED);     // Optional, remove if you don't need.

Now, call the createOrUpdateEnrollmentGroup on the ProvisioningServiceClient to create a new enrollmentGroup.

// *************************************** Create a new enrollment group ***************************************
System.out.println("\nAdd new enrollmentGroup...");
EnrollmentGroup enrollmentGroupResult =  provisioningServiceClient.createOrUpdateEnrollmentGroup(enrollmentGroup);
System.out.println("\nEnrollmentGroup created with success...");
System.out.println(enrollmentGroupResult);

Save and close the app.java file.

Build and run the App as you did in the item 8.

The App should print something like:

Beginning my sample for the Provisioning Service Client!

Create new enrollmentGroup config...

Add new enrollmentGroup...

EnrollmentGroup created with success...
{
    "enrollmentGroupId":"enrollmentgroupid-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "attestation":{
        "type":"x509",
        "signingCertificates":{
            "primary":{
                "info": {
                    "subjectName": "CN=ROOT_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, OU=Azure IoT, O=MSFT, C=US",
                    "sha1Thumbprint": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                    "sha256Thumbprint": "validEnrollmentGroupId",
                    "issuerName": "CN=ROOT_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, OU=Azure IoT, O=MSFT, C=US",
                    "notBeforeUtc": "2017-11-14T12:34:18Z",
                    "notAfterUtc": "2017-11-20T12:34:18Z",
                    "serialNumber": "xxxxxxxxxxxxxxxxxx",
                    "version": 3
                }
            }
        }
    },
    "iotHubHostName":"ContosoIoTHub.azure-devices.net",
    "provisioningStatus":"enabled",
    "etag": "\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\""
}

Check in the Azure Portal if your enrollmentGroup was created with success.
Delete the EnrollmentGroup using the Portal, or create a new certificate for the next test.

Check the created enrollmentGroup information in your App. You can consult using 2 ProvisioningServiceClient APIs, get and query.

Use the getEnrollmentGroup to get an specific enrollmentGroup using the EnrollmentGroupId. Add the following code.

// **************************************** Get info of enrollmentGroup ****************************************
System.out.println("\nGet the enrollmentGroup information...");
EnrollmentGroup getResult = provisioningServiceClient.getEnrollmentGroup(enrollmentGroupId);
System.out.println(getResult);

Use the createEnrollmentGroupQuery to create a query for the enrollmentGroups in the provisioning service. The QuerySpecificationBuilder will help you to create a correct QuerySpecification. For this sample, we will query all "*" enrollmentGroups is the provisioning service.

// *************************************** Query info of enrollmentGroup ***************************************
System.out.println("\nCreate a query for the enrollmentGroups...");
QuerySpecification querySpecification =
        new QuerySpecificationBuilder("*", QuerySpecificationBuilder.FromType.ENROLLMENT_GROUPS)
                .createSqlQuery();
Query query = provisioningServiceClient.createEnrollmentGroupQuery(querySpecification);

while(query.hasNext())
{
    System.out.println("\nQuery the next enrollmentGroups...");
    QueryResult queryResult = query.next();
    System.out.println(queryResult);
}

Delete the enrollmentGroup from the provisioning service. You can delete the enrollmentGroup adding the following code that invokes the API deleteEnrollmentGroup:

// ************************************** Delete info of enrollmentGroup ***************************************
System.out.println("\nDelete the enrollmentGroup...");
provisioningServiceClient.deleteEnrollmentGroup(enrollmentGroupId);

Save and close the app.java file.
Build and run the App as you did in the item 8. Check the results on your console. Note that you will not see any new enrollmentGroup in the Azure Portal, because we are deleting it in the item 19.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

service-enrollment-group-sample

service-enrollment-group-sample

readme.md

Provisioning Service Client Sample For EnrollmentGroup

Overview

References

How to run the samples on Linux or Windows

How to create a new provisioning App, step by step

Files

service-enrollment-group-sample

Directory actions

More options

Directory actions

More options

Latest commit

History

service-enrollment-group-sample

Folders and files

parent directory

readme.md

Provisioning Service Client Sample For EnrollmentGroup

Overview

References

How to run the samples on Linux or Windows

How to create a new provisioning App, step by step