Automated deployment - Virtual Andon on AWS

Automated deployment

Before you launch the automated deployment, review the architecture, configuration, and other considerations in this guide. Follow the step-by-step instructions in this section to configure and deploy the Virtual Andon on AWS solution into your account.

Time to deploy: Approximately 15 minutes

Deployment overview

The procedure for deploying this architecture on AWS consists of the following steps. For detailed instructions, follow the links for each step.

Note

For information about updating this solution, refer to Solution updates in this guide.

Step 1. Launch the stack

  • Launch the AWS CloudFormation template into your AWS account.

  • Enter a value for the required parameter: AdministratorEmail.

Step 2. Sign in to the web interface

  • Sign in to the web interface using your email address and temporary password.

Step 3. Add users

  • Add the people in your organization that require access to the web interface.

Step 4. Add the root causes

  • Add the root causes for events you identify in the solution.

Step 5. Add site details

  • Add sites and set up the factory details.

  • Optional: Configure Amazon Lookout for Equipment

  • Optional: Configure IoT devices

Step 6. Add permissions for users in the Associate Group

  • Add permissions for the users that are in the Associate Group.

Step 1. Launch the stack

Important

This solution includes an option to send anonymous operational metrics to AWS. We use this data to better understand how customers use this solution and related services and products. AWS owns the data gathered though this survey. Data collection is subject to the AWS Privacy Policy.

To opt out of this feature, download the template, modify the AWS CloudFormation mapping section, and then use the AWS CloudFormation console to upload your template and deploy the solution. For more information, refer to the Collection of operational metrics section of this guide.

This automated AWS CloudFormation template deploys Virtual Andon on AWS in the AWS Cloud.

Note

You are responsible for the cost of the AWS services used while running this solution. Refer to the Cost section for more details. For full details, refer to the pricing webpage for each AWS service used in this solution.

  1. Sign in to the AWS Management Console and use the button below to launch the amazon-virtual-andon AWS CloudFormation template.

    
                Virtual Andon on AWS launch button

    You can also download the template as a starting point for your own implementation.

  2. The template launches in the US East (N. Virginia) Region by default. To launch the solution in a different AWS Region, use the Region selector in the console navigation bar.

    Note

    This solution uses AWS AppSync and Amazon Cognito, which are currently available in specific AWS Regions only. Therefore, you must launch this solution in an AWS Region where these AWS services are available. For the most current availability by Region, refer to the AWS Regional Services List.

  3. On the Create stack page, verify that the correct template URL shows in the Amazon S3 URL text box and choose Next.

  4. On the Specify stack details page, assign a name to your solution stack.

  5. Under Parameters, review the parameters for the template and modify them as necessary. This solution uses the following default values.

    Parameter Default Description

    AdministratorEmail

    <Requires input> Email address for the Virtual Andon on AWS administrator. The Admin receives an SNS message containing the web interface URL and sign in credentials.

    DefaultLanguage

    Browser default Virtual Andon on AWS web interface default language. Default value is “Browser Default” which supports the web browser’s language as a default language.

    LogLevel

    ERROR The logging level for AWS Lambda functions and the solution’s web interface. The default level is set to ERROR, and additional levels include INFO, WARN, VERBOSE, and DEBUG.

    Activate Glue Workflow

    No If set to Yes, the solution runs a data extraction weekly (Monday at 1:00 AM UTC) from DynamoDB to Amazon S3 using an AWS Glue workflow. After the workflow runs, the data from the two data tables: data hierarchy and issues, are exported into an Amazon S3 bucket. The data can then be imported to an analytics tool or queried ad-hoc using Amazon Athena.
    Anomaly Detection Output Bucket <Optional input> This parameter is used only with Amazon Lookout for Equipment. Enter the name of the Amazon S3 bucket where anomaly files should be stored. These anomaly files can then be used to automatically create Issues within this solution.
    Cognito Domain Prefix <Optional input> This parameter is used only when configuring a third-party SAML identity provider. The prefix to the Amazon Cognito hosted domain name that will be associated with the user pool.
    SAML Provider Name <Optional input> This parameter is used only when configuring a third-party SAML identity provider. The identity provider name.
    SAML Provider Metadata Url <Optional input> This parameter is used only when configuring a third-party SAML identity provider. Metadata URL for the identity provider details.
  6. Choose Next.

  7. On the Configure stack options page, choose Next.

  8. On the Review page, review and confirm the settings. Check the boxes acknowledging that the template creates AWS Identity and Access Management (IAM) resources and may require an AWS CloudFormation capability.

    Note

    This solution may require an AWS CloudFormation capability: CAPABILITY_AUTO_EXPAND, which is a parameter that supports the use of macros. For information about this AWS CloudFormation capability, refer to CreateStack in the AWS CloudFormation API Reference.

  9. Choose Create stack to deploy the stack.

    You can view the status of the stack in the AWS CloudFormation console in the Status column. You should receive a CREATE_COMPLETE status in approximately 15 minutes.

Note

You will receive an email containing your login information before the stack creation process is completed. Wait until you receive a CREATE_COMPLETE status before accessing and signing in to the Virtual Andon on AWS web interface.

Step 2. Sign in to the web interface

After the AWS CloudFormation stack creation completes, the resources for the web interface are deployed. Use the email you received to obtain the URL for the web interface and your admin credentials, which include a temporary password.

  1. Open the email and select the URL link.

  2. On the Virtual Andon on AWS sign in page, enter your admin email address and temporary password.

  3. On the Change Password page, enter a new password.

    Note

    Password requirements—minimum of eight characters, requiring at least one upper case character, one number, and one symbol.

  4. Optional: On the Account recovery page, select E-Mail to receive a code to verify your contact information. You can skip the account recovery setup.

After you sign in to the web interface, follow the remaining steps to set up the factory details, including adding users, creating the root causes, and other information.

Step 3. Add users

Use the following procedure to add the users in your organization that require access to the web interface. These users include additional administrators for this solution, managers that analyze metrics-related issues, engineers that troubleshoot issues, and other users.

  1. From the Virtual Andon on AWS homepage, choose Users.

  2. You can manually create users in the web interface, or use the provided CSV template to add multiple users.

    • Use the following steps to manually create a new user:

      1. Choose Add User.

      2. Enter the user’s email address to receive automated notifications from the solution.

      3. Under Groups, check the appropriate group(s) for this user.

      4. Choose Add.

      5. Repeat these steps to continue adding users manually.

    • To add multiple users at once, take the following steps:

      1. Choose Download CSV.

      2. Open the CSV file and enter the following information:

        • For username, enter the email addresses for the users requiring access to the web interface.

        • For groups, enter the name of the group(s) for each user in the following format: AdminGroup, ManagerGroup, EngineerGroup, or AssociateGroup.

          Note

          If a user belongs to more than one group, use a comma to separate the group names.

        • Save the CSV file.

      3. In the web interface, choose Upload CSV, select the appropriate CSV file, and choose Upload. The web interface adds the users identified in the CSV file automatically.

Note

Because users can be assigned to more than one group, a user inherits the permissions of the group with the highest access level. After a user is added to a group, they receive an email with a temporary password to sign in to the web interface. For information about groups, refer to Amazon Cognito user groups.

Step 4. Add the root causes

Root causes link to events. An event can be initiated by one or more root causes and administrators can define common root causes for events using the web interface. Therefore, root causes must be defined first before they can be linked to root causes. From the Root Causes page, use the following procedure to either manually enter root causes one at a time using the web interface, or use the included CSV file to upload multiple root causes.

  1. From the Virtual Andon on AWS homepage, choose Root Causes.

  2. Choose one of the following options to create the root causes:

    • Use the following steps to manually create a root cause:

      1. Choose Add Root Cause.

      2. In the Add Root Cause dialog box, enter a root cause and choose Add.

      3. Repeat these steps to continue adding root causes manually.

    • To use the included CSV file, take the following steps:

      1. Choose Download CSV.

      2. Enter the root causes in the CSV file. Enter only one root cause in each row.

      3. Save the CSV file.

      4. Choose Upload CSV, select the CSV file, and choose Upload.

Step 5. Add site details

The solution administrator adds the site details for the solution to monitor. Use the following procedure to add site details.

  1. From the Virtual Andon on AWS homepage, choose Sites.

  2. From the Sites page, choose Add Site.

  3. In the Site Registration dialog box, enter the Site Name and Site Description.

  4. Choose Register.

After a site is created in the web interface, you can add the necessary details. Use the following procedure to add Areas, Stations, Devices, Processes, and Events. The following details are required: at least one process and station in an area and at least one device in each station for each area you identify.

  1. From the Sites page, identify the site to add details to and choose Detail.

  2. From the Areas page, choose Add Area.

  3. In the Area Registration dialog box, enter the Area Name and Area Description and choose Register.

    Note

    You can continue to add areas from the Areas page.

  4. From the Areas page, in the section displaying the name of the area you created, choose Stations.

  5. On the Stations page, choose Add Station.

  6. In the Station Registration dialog box, enter the Station Name and Station Description and choose Register.

    Note

    You can continue to add stations from the Stations page.

  7. From the Stations page, in the Station section, choose Details.

  8. On the Devices page, choose Add Device.

  9. In the Device Registration dialog box, enter the Device Name and Device Description.

  10. Optionally, enter the Device Alias.

  11. Choose Register.

    Note

    You can continue to add devices from the Devices page.

  12. To add a process, select the name of the area that you created from the navigation bar.

  13. From the Areas page, in the section displaying the name of the area, choose Processes.

  14. Choose Add Process.

  15. In the Process Registration dialog box, enter the Process Name and Process Description and choose Register.

    Note

    You can continue to add processes from the Processes page.

  16. To add an event to the process you just created, locate the name of the process and choose Detail.

  17. On the Events page, choose Add Event.

  18. In the Event Registration dialog box, enter the following required information:

    1. Event Name

    2. Event Description

    3. Event Priority

    4. Optionally, enter a group email address, SMS number, Event Type, and, if available, select the root causes for this event.

      Note

      You can enter multiple SMS numbers and email addresses using a comma-separated list.

    5. Optionally, insert an image to be associated with the event.

  19. Choose Save.

    Note

    You can continue to add events from the Events page.

You can add sub events to an event after it is created. For guidance to add sub events and to edit the site details, refer to Solution web interface.

Optional: Configure Amazon Lookout for Equipment

If you are integrating Amazon Lookout for Equipment, you can create an automated event in the solution’s web console by taking the following steps.

  1. Follow Step 5 for creating Sites, Areas, and Processes.

  2. To add an event to a process, locate the name of the process and choose Detail.

  3. On the Events page, choose Add Event.

  4. In the Event Registration dialog box, enter the following required information:

    1. Enter an Event Name.

    2. Enter an Event Description.

    3. For Event Type, enter automated as the value.

    4. Select an Event Priority.

    5. Optionally, enter a group email address, SMS number, and, if available, select the root causes for this event.

    6. Optionally, insert an image to be associated with the event

  5. On the Devices page, choose Add Device.

  6. In the Device Registration dialog box, enter the following required information:

    1. Enter a device name.

    2. Enter a description for your device.

    3. For Device Alias, enter the name of the machine as it will appear in the diagnostic data reported by Lookout for Equipment. Do not include a specific sensor name; only the name of the machine is required.

Optional: Configure IoT devices

The following messages code sample shows an example message setup that can be sent to the ava/devices IoT Core topic.

{ “messages”: [ { “name”: “site/area/process/machine/status”, “timestamp”: “2021-03-31 00:15:28.487000+00:00”, “quality”: “GOOD”, “value”: “down” } ] }

Once configured, the IoT device invokes an AWS Lambda function, which takes the following actions:

  1. Retrieves the last element (most recent) from the messages array.

  2. Parses the name field to extract the machine and tag names.

    The name field is split by a delimiter (forward slash) and the final value becomes the tag name. The remaining name string is used as the device name. For example, using the code sample:

    • The device name would be site/area/process/machine

    • The tag name would be status

  3. The tag value is taken from the message’s value property. In the code sample, down is the tag value.

To ensure your IoT devices are properly connected to Virtual Andon on AWS, take the following steps:

  1. Follow Step 5 for creating Sites, Areas, and Stations.

  2. From the Stations page, in the Station section, choose Details.

  3. On the Devices page, choose Add Device.

  4. In the Device Registration dialog box, enter the Device Name and Device Description.

  5. Use the IoT device name as the Device Alias. For example, in the messages code sample, you would enter site/area/process/machine in the Device Alias field in Amazon Virtual Andon.

Registering a device that has an alias

Figure 6: Registering a device that has an alias

To associate an Virtual Andon on AWS Event with a specific tag and value, use the tag name and value separated by an underscore as the Event Alias when creating the new event. In the messages code sample, the Event Alias is status_down.

Registering an event containing an alias

Figure 7: Registering an event containing an alias

If an Event and Device are matched, an Issue is raised in Amazon Virtual Andon.

Note

The Device and Event must belong to the same Process.

Step 6. Add permissions for users in the Associate Group

Use the following procedure to add permissions for users in the Associate Group.

  1. From the Virtual Andon on AWS homepage, choose Permissions.

  2. Choose Add Permission.

  3. On the Permissions / Permissions Setting page, select the user’s email.

  4. From the list of sites, select the checkbox next to the site name. A list of Areas available for that site displays.

  5. For each Area, select the checkbox next to the processes, stations, and devices to grant access permission to the user.

After the permission is set, the user can access the site information from the Client page. For information about editing or removing a user’s permission in the Associate Group, refer to Solution web interface.