Skip to content

Commit eddbf02

Browse files
scmacdonscmacdon
committed
add a new location for Basic Specs
1 parent 2139d5f commit eddbf02

File tree

2 files changed

+367
-0
lines changed

2 files changed

+367
-0
lines changed

‎scenarios/basics/entity_resolution/README.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
## Overview
2+
This AWS IoT SiteWise Service basic scenario demonstrates how to interact with the AWS IoT SiteWise service using an AWS SDK. The scenario covers various operations such as creating an Asset Model, creating assets, sending data to assets, and retrieving data.
3+
4+
## Key Operations
5+
6+
1. **Create an AWS SiteWise Asset Model**:
7+
- This step creates an AWS SiteWise Asset Model by invoking the `createAssetModel` method.
8+
9+
2. **Create an AWS IoT SiteWise Asset**:
10+
- This operation creates an AWS SiteWise asset.
11+
12+
3. **Retrieve the property ID values**:
13+
- To send data to an asset, we need to get the property ID values for the model properties. This scenario uses temperature and humidity properties.
14+
15+
4. **Send data to an AWS IoT SiteWise Asset**:
16+
- This operation sends data to an IoT SiteWise Asset.
17+
18+
5. **Retrieve the value of the IoT SiteWise Asset property**:
19+
- This operation gets data from the asset.
20+
21+
**Note** See the Eng spec for a full listing of operations.
22+
23+
## Resources
24+
25+
This Basics scenario requires an IAM role that has permissions to work with the AWS IoT SiteWise service. The scenario creates this resource using a CloudFormation template.
26+
27+
## Implementations
28+
29+
This scenario example will be implemented in the following languages:
30+
31+
- Java
32+
- Python
33+
- JavaScript
34+
35+
## Additional Reading
36+
37+
- [AWS IoT SiteWise Documentation](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html)
38+
39+
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: Apache-2.0

‎scenarios/basics/entity_resolution/SPECIFICATION.md‎

Lines changed: 328 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,328 @@
1+
# AWS Entity Resolution Service Scenario Specification
2+
3+
## Overview
4+
This SDK Basics scenario demonstrates how to interact with AWS Entity Resolution using an AWS SDK. It demonstrates various tasks such as creating a Schema Mapping, creating an matching workflow, starting the workflow, and so on. Finally this scenario demonstrates how to clean up resources. Its purpose is to demonstrate how to get up and running with AWS Entity Resolution and an AWS SDK.
5+
6+
## Resources
7+
This Basics scenario requires an IAM role that has permissions to work with the AWS Entity Resolution service, an AWS Glue database and a table, and two S3 buckets. A CDK script is provided to create these resources.
8+
9+
## Hello AWS Entity Resolution
10+
This program is intended for users not familiar with the AWS Entity Resolution Service to easily get up and running. The program uses a `listIdMappingJobsPaginator` to demonstrate how you can read through workflow job information.
11+
12+
## Basics Scenario Program Flow
13+
The AWS Entity Resolution Basics scenario executes the following operations.
14+
15+
1. **Create a Schema Mapping**:
16+
- Description: Creates a schema mapping invoking the `createSchemaMapping` method.
17+
- Exception Handling: Check to see if a `ConflictException` is thrown.
18+
If it is thrown, display the information and end the program.
19+
20+
2. **Create a Matching Workflow**:
21+
- Description: Creates a new matching workflow, defining how entities should be resolved and matched..
22+
- The method `createMatchingWorkflow` is called.
23+
- Exception Handling: Check to see if a `ConflictException` is thrown if a conflict in the current state of the resource exists. If so,
24+
display the message and end the program.
25+
26+
3. **Start Matching Workflow**:
27+
- Description: Initiates a matching workflow to process entity resolution based on predefined configurations.
28+
- The method `listAssetModelProperties` is called to retrieve the property ID values.
29+
- Exception Handling: Check to see if an `IoTSiteWiseException` is thrown. There are not
30+
many other useful exceptions for this specific call. If so, display the message and end the program.
31+
32+
4. **Send data to an AWS IoT SiteWise Asset**:
33+
- Description: This operation sends data to an IoT SiteWise Asset.
34+
- This step uses the method `batchPutAssetPropertyValue`.
35+
- Exception Handling: Check to see if a `ResourceNotFoundException` is thrown. If so, display the message and end the program.
36+
37+
5. **Retrieve the value of the IoT SiteWise Asset property**:
38+
- Description: This operation gets data from the asset.
39+
- This step uses the method `getAssetPropertyValue`.
40+
- Exception Handling: Check to see if a `ResourceNotFoundException` is thrown. If so, display the message and end the program.
41+
42+
6. **Create an IoT SiteWise Portal**:
43+
- Description: This operation creates an IoT SiteWise portal.
44+
- The method `createPortal` is called.
45+
- Exception Handling: Check to see if an `IoTSiteWiseException` is thrown. If so, display the message and end the program.
46+
47+
7. **Describe the Portal**:
48+
- Description: This operation describes the portal and returns a URL for the portal.
49+
- The method `describePortal` is called and returns the URL.
50+
- Exception Handling: Check to see if a `ResourceNotFoundException` is thrown. If so, display the message and end the program.
51+
52+
8. **Create an IoT SiteWise Gateway**:
53+
- Description: This operation creates an IoT SiteWise Gateway.
54+
- The method `createGateway` is called.
55+
- Exception Handling: Check to see if an `IoTSiteWiseException` is thrown. If so, display the message and end the program.
56+
57+
9. **Describe the IoT SiteWise Gateway**:
58+
- Description: This operation describes the Gateway.
59+
- The method `describeGateway` is called.
60+
- Exception Handling: Check to see if a `ResourceNotFoundException` is thrown. If so, display the message and end the program.
61+
62+
10. **Delete the AWS IoT SiteWise Assets**:
63+
- The `delete` methods are called to clean up the resources.
64+
- Exception Handling: Check to see if a `ResourceNotFoundException` is thrown. If so, display the message and end the program."
65+
66+
### Program execution
67+
The following shows the output of the AWS IoT SiteWise Basics scenario in the console.
68+
69+
```
70+
AWS IoT SiteWise is a fully managed industrial software-as-a-service (SaaS) that
71+
makes it easy to collect, store, organize, and monitor data from industrial equipment and processes.
72+
It is designed to help industrial and manufacturing organizations collect data from their equipment and
73+
processes, and use that data to make informed decisions about their operations.
74+
75+
One of the key features of AWS IoT SiteWise is its ability to connect to a wide range of industrial
76+
equipment and systems, including programmable logic controllers (PLCs), sensors, and other
77+
industrial devices. It can collect data from these devices and organize it into a unified data model,
78+
making it easier to analyze and gain insights from the data. AWS IoT SiteWise also provides tools for
79+
visualizing the data, setting up alarms and alerts, and generating reports.
80+
81+
Another key feature of AWS IoT SiteWise is its ability to scale to handle large volumes of data.
82+
It can collect and store data from thousands of devices and process millions of data points per second,
83+
making it suitable for large-scale industrial operations. Additionally, AWS IoT SiteWise is designed
84+
to be secure and compliant, with features like role-based access controls, data encryption,
85+
and integration with other AWS services for additional security and compliance features.
86+
87+
Let's get started...
88+
89+
90+
Enter 'c' followed by <ENTER> to continue:
91+
c
92+
Continuing with the program...
93+
94+
--------------------------------------------------------------------------------
95+
Use AWS CloudFormation to create an IAM role that are required for this scenario.
96+
Stack creation requested, ARN is arn:aws:cloudformation:us-east-1:814548047983:stack/RoleSitewise/29f480c0-75fd-11ef-a42e-12cd4e534049
97+
Stack created successfully
98+
--------------------------------------------------------------------------------
99+
1. Create an AWS SiteWise Asset Model
100+
An AWS IoT SiteWise Asset Model is a way to represent the physical assets, such as equipment,
101+
processes, and systems, that exist in an industrial environment. This model provides a structured and
102+
hierarchical representation of these assets, allowing users to define the relationships and properties
103+
of each asset.
104+
105+
106+
Enter 'c' followed by <ENTER> to continue:
107+
c
108+
Continuing with the program...
109+
110+
The Asset Model MyAssetModel already exists. The id of the existing model is ffbc475b-73ad-4eb6-bf28-8728818fa8ef. Moving on...
111+
112+
Enter 'c' followed by <ENTER> to continue:
113+
c
114+
Continuing with the program...
115+
116+
--------------------------------------------------------------------------------
117+
2. Create an AWS IoT SiteWise Asset
118+
The IoT SiteWise model defines the structure and metadata for your physical assets. Now we
119+
can use the asset model to create the asset.
120+
121+
122+
123+
Enter 'c' followed by <ENTER> to continue:
124+
c
125+
Continuing with the program...
126+
127+
Asset created with ID: 4d681624-a303-46dd-8830-6189790ae915
128+
129+
Enter 'c' followed by <ENTER> to continue:
130+
c
131+
Continuing with the program...
132+
133+
--------------------------------------------------------------------------------
134+
--------------------------------------------------------------------------------
135+
3. Retrieve the property ID values
136+
To send data to an asset, we need to get the property ID values for the
137+
Temperature and Humidity properties.
138+
139+
140+
Enter 'c' followed by <ENTER> to continue:
141+
c
142+
Continuing with the program...
143+
144+
The Humidity property Id is feb4aba6-55f9-4b00-b366-27b9d7e5a747
145+
The Temperature property Id is 6cb505aa-6bcc-46f4-a12a-7ca5df8eb028
146+
147+
Enter 'c' followed by <ENTER> to continue:
148+
c
149+
Continuing with the program...
150+
151+
--------------------------------------------------------------------------------
152+
--------------------------------------------------------------------------------
153+
4. Send data to an AWS IoT SiteWise Asset
154+
By sending data to an IoT SiteWise Asset, you can aggregate data from
155+
multiple sources, normalize the data into a standard format, and store it in a
156+
centralized location. This makes it easier to analyze and gain insights from the data.
157+
158+
This example demonstrate how to generate sample data and ingest it into the AWS IoT SiteWise asset.
159+
160+
161+
162+
Enter 'c' followed by <ENTER> to continue:
163+
c
164+
Continuing with the program...
165+
166+
Data sent successfully.
167+
168+
Enter 'c' followed by <ENTER> to continue:
169+
c
170+
Continuing with the program...
171+
172+
--------------------------------------------------------------------------------
173+
--------------------------------------------------------------------------------
174+
5. Retrieve the value of the IoT SiteWise Asset property
175+
IoT SiteWise is an AWS service that allows you to collect, process, and analyze industrial data
176+
from connected equipment and sensors. One of the key benefits of reading an IoT SiteWise property
177+
is the ability to gain valuable insights from your industrial data.
178+
179+
180+
181+
Enter 'c' followed by <ENTER> to continue:
182+
c
183+
Continuing with the program...
184+
185+
The property name is: Temperature property
186+
The value of this property is 23.5
187+
188+
Enter 'c' followed by <ENTER> to continue:
189+
c
190+
Continuing with the program...
191+
192+
The property name is: Humidity property
193+
The value of this property is 65.0
194+
195+
Enter 'c' followed by <ENTER> to continue:
196+
c
197+
Continuing with the program...
198+
199+
--------------------------------------------------------------------------------
200+
--------------------------------------------------------------------------------
201+
6. Create an IoT SiteWise Portal
202+
An IoT SiteWise Portal allows you to aggregate data from multiple industrial sources,
203+
such as sensors, equipment, and control systems, into a centralized platform.
204+
205+
206+
Enter 'c' followed by <ENTER> to continue:
207+
c
208+
Continuing with the program...
209+
210+
Portal created successfully. Portal ID 63e65729-b7a1-410a-aa36-94145fe92153
211+
The portal Id is 63e65729-b7a1-410a-aa36-94145fe92153
212+
213+
Enter 'c' followed by <ENTER> to continue:
214+
c
215+
Continuing with the program...
216+
217+
--------------------------------------------------------------------------------
218+
--------------------------------------------------------------------------------
219+
7. Describe the Portal
220+
In this step, we will describe the step and provide the portal URL.
221+
222+
223+
Enter 'c' followed by <ENTER> to continue:
224+
c
225+
Continuing with the program...
226+
227+
Portal URL: https://p-fy9qnrqy.app.iotsitewise.aws
228+
229+
Enter 'c' followed by <ENTER> to continue:
230+
c
231+
Continuing with the program...
232+
233+
--------------------------------------------------------------------------------
234+
--------------------------------------------------------------------------------
235+
8. Create an IoTSitewise Gateway
236+
IoTSitewise Gateway serves as the bridge between industrial equipment, sensors, and the
237+
cloud-based IoTSitewise service. It is responsible for securely collecting, processing, and
238+
transmitting data from various industrial assets to the IoTSitewise platform,
239+
enabling real-time monitoring, analysis, and optimization of industrial operations.
240+
241+
242+
243+
Enter 'c' followed by <ENTER> to continue:
244+
c
245+
Continuing with the program...
246+
247+
The ARN of the gateway is arn:aws:iotsitewise:us-east-1:814548047983:gateway/50320670-1d88-4a7e-9013-1d7e8a3af832
248+
Gateway creation completed successfully. id is 50320670-1d88-4a7e-9013-1d7e8a3af832
249+
--------------------------------------------------------------------------------
250+
--------------------------------------------------------------------------------
251+
9. Describe the IoTSitewise Gateway
252+
253+
Enter 'c' followed by <ENTER> to continue:
254+
c
255+
Continuing with the program...
256+
257+
Gateway Name: myGateway11
258+
Gateway ARN: arn:aws:iotsitewise:us-east-1:814548047983:gateway/50320670-1d88-4a7e-9013-1d7e8a3af832
259+
Gateway Platform: GatewayPlatform(GreengrassV2=GreengrassV2(CoreDeviceThingName=myThing78))
260+
Gateway Creation Date: 2024-09-18T20:34:13.117Z
261+
--------------------------------------------------------------------------------
262+
--------------------------------------------------------------------------------
263+
10. Delete the AWS IoT SiteWise Assets
264+
Before you can delete the Asset Model, you must delete the assets.
265+
266+
267+
Would you like to delete the IoT Sitewise Assets? (y/n)
268+
y
269+
You selected to delete the Sitewise assets.
270+
271+
Enter 'c' followed by <ENTER> to continue:
272+
c
273+
Continuing with the program...
274+
275+
Portal 63e65729-b7a1-410a-aa36-94145fe92153 was deleted successfully.
276+
An unexpected error occurred: Cannot invoke "java.util.concurrent.CompletableFuture.join()" because "future" is null
277+
Asset deleted successfully.
278+
Lets wait 1 min for the asset to be deleted
279+
01:00The Gateway was deleted successfully
280+
00:00Countdown complete!
281+
282+
Enter 'c' followed by <ENTER> to continue:
283+
c
284+
Continuing with the program...
285+
286+
Delete the AWS IoT SiteWise Asset Model
287+
Asset model deleted successfully.
288+
289+
Enter 'c' followed by <ENTER> to continue:
290+
c
291+
Continuing with the program...
292+
293+
--------------------------------------------------------------------------------
294+
--------------------------------------------------------------------------------
295+
Delete stack requested ....
296+
Stack deleted successfully.
297+
This concludes the AWS SiteWise Scenario
298+
--------------------------------------------------------------------------------
299+
300+
301+
```
302+
303+
## SOS Tags
304+
305+
The following table describes the metadata used in this Basics Scenario.
306+
307+
308+
| action | metadata file | metadata key |
309+
|--------------------------------|-----------------------------------|---------------------------------------- |
310+
| `describeGateway` | iot_sitewise_metadata.yaml | iotsitewise_DescribeGateway |
311+
| `deleteGateway ` | iot_sitewise_metadata.yaml | iotsitewise_DeleteGateway |
312+
| `createGateway ` | iot_sitewise_metadata.yaml | iotsitewise_CreateGateway |
313+
| `describePortal` | iot_sitewise_metadata.yaml | iotsitewise_DescribePortal |
314+
| `listAssetModels` | iot_sitewise_metadata.yaml | iotsitewise_ListAssetModels |
315+
| `deletePortal` | iot_sitewise_metadata.yaml | iotsitewise_DeletePortal |
316+
| `createPortal` | iot_sitewise_metadata.yaml | iotsitewise_CreatePortal |
317+
| `deleteAssetModel` | iot_sitewise_metadata.yaml | iotsitewise_DeleteAssetModel |
318+
| `deleteAsset` | iot_sitewise_metadata.yaml | iotsitewise_DeleteAsset |
319+
| `describeAssetModel` | iot_sitewise_metadata.yaml | iotsitewise_DescribeAssetModel |
320+
| `getAssetPropertyValue` | iot_sitewise_metadata.yaml | iotsitewise_GetAssetPropertyValue |
321+
| `batchPutAssetPropertyValue` | iot_sitewise_metadata.yaml | iotsitewise_BatchPutAssetPropertyValue |
322+
| `createAsset` | iot_sitewise_metadata.yaml | iotsitewise_CreateAsset |
323+
| `createAssetModel ` | iot_sitewise_metadata.yaml | iotsitewise_CreateAssetModel |
324+
| `scenario` | iot_sitewise_metadata.yaml | iotsitewise_Scenario |
325+
| `hello` | iot_sitewise_metadata.yaml | iotsitewise_Hello |
326+
327+
328+

0 commit comments

Comments
 (0)