Website monitoring with SimWorkflow

This tutorial shows how to create and test a workflow definition that monitors a website for uptime. Use third party APIs to send email alerts, SMS alerts, and Slack messages when the website is down.

• Prerequisites
• Step 1: Sign up to an SMS gateway
• Step 2: Setup sandbox destination phone numbers
• Step 3: Create Identity and Access Management (IAM) policy to publish SMS messages
• Step 4: Create IAM user with AmazonSNSPublishSMS policy
• Step 5: Create access key and secret access key for user_to_send_sms user
• Step 6: Create AWS credentials
• Step 7: Sign up to Slack
• Step 8: Create a Slack app
• Step 9: Request scopes for Slack app
• Step 10: Installing and authorizing the Slack app
• Step 11: Create Slack OAuth 2.0 credentials
• Step 12: Create SimWorkflow Personal Access Token
• Step 13: Create SimWorkflow Bearer token credentials
• Step 14: Create SimWorkflow workflow definitions
  • Step 14.1: Plan error handling workflow definition
  • Step 14.2: Define error handling workflow definition
  • Step 14.3: Define monitor website workflow definition
• Step 15: Define variables
  • Step 15.1: URL to check
  • Step 15.2: Email address
  • Step 15.4: AWS region
• Step 16: Run the workflow definition
• Step 17: Define the schedule with cron expression
• Summary

Prerequisites

To perform the steps in this tutorial, you must already have the following:

• An account with a third-party SMS gateway to send SMS messages.
• An account with Slack to send Slack messages.
• A SimWorkflow account that you can log in to create pages and workflow definitions.

Step 1: Sign up to an SMS gateway

An SMS gateway is required to send SMS messages.

For this tutorial, we're using Amazon Simple Notification Service (SNS).

If you're a first-time user of AWS, your first step is to sign up for an AWS account.

Step 2: Setup sandbox destination phone numbers

1. Login to AWS.
2. Navigate to AWS Console.
3. Select an AWS region.
4. Click Services and select Simple Notification Service.
5. Under Mobile left menu, click Text messaging (SMS).
6. Click Add phone number button in Sandbox destination phone numbers section.
7. Enter the phone number to receive text SMS messages.
8. Click Add phone number button.

Step 3: Create Identity and Access Management (IAM) policy to publish SMS messages

1. On AWS Console.

2. Click Services and select IAM.

3. Under Access management left menu, click Policies.

4. Click Create policy button in Policies section.

5. Select JSON Policy editor.

6. Define the following policy to allow sns:Publish action:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "sns:Publish"
         ],
         "Resource": "*"
       }
     ]
   }
   

7. Click Next button.

8. Enter the policy name. For this tutorial, we're using AmazonSNSPublishSMS.

9. Click Create policy button.

Step 4: Create IAM user with AmazonSNSPublishSMS policy

1. On AWS Console.
2. Click Services and select IAM.
3. Under Access management left menu, click Users.
4. Click Create user button in Users section.
5. Enter the username. For this tutorial, we're using user_to_send_sms.
6. Click Next button.
7. Select Attach policies directly for Permissions options.
8. Search for AmazonSNSPublishSMS and check its checkbox.
9. Click Next button.
10. Click Create user button.

Step 5: Create access key and secret access key for user_to_send_sms user

1. On AWS Console.
2. Click Services and select IAM.
3. Under Access management left menu, click Users.
4. Select user_to_send_sms from the Users section.
5. Click Create access key for Access key 1 in Summary section.
6. Select Command Line Interface (CLI) for Use case.
7. Check Confirmation checkbox.
8. Click Next button.
9. Enter the description.
10. Click Next button.
11. Copy Access key, we'll paste it later.
12. Copy Secret access key, we'll paste it later.
13. Click Done button.

Step 6: Create AWS credentials

1. Log in to the SimWorkflow.

2. Navigate to Credentials.

3. Click Create credentials button.

4. Select AWS tab.

5. Enter Amazon SNS in the Name field.

6. Paste the Access key in the Access key ID field.

7. Paste the Secret access key in the Secret access key field.

8. Click Create credentials button.

We'll use this credentials in the workflow definition when we integrate with AWS SNS to send SMS alerts.

Step 7: Sign up to Slack

If you're a first-time user of Slack, your first step is to sign up for a Slack account.

Step 8: Create a Slack app

1. On the Your Apps page, select Create New App.

2. Select From scratch.

3. Enter SimWorkflow in the App Name field.

4. Select the Workspace where you'll be developing your app.

5. Select Create App.

Step 9: Request scopes for Slack app

1. Within OAuth & Permissions, scroll down to Scopes.

2. Under Bot Token Scopes, select Add an OAuth Scope.

3. To allow your app to post messages, add the chat:write scope.

Step 10: Installing and authorizing the Slack app

1. Return to the Basic Information section of the app management page.

2. Install your app by selecting the Install to Workspace button.

3. You'll now be sent through the Slack OAuth flow. Select Allow on the following screen.

4. After installation, navigate back to the OAuth & Permissions page.

5. Click Add New Redirect URL button under Redirect URLs.

6. Enter https://www.simworkflow.com/credentials/callback to the input field and click Add button.

7. Return to the Basic Information section of the app management page.

8. Under App Credentials, copy Client ID and Client Secret.

Step 11: Create Slack OAuth 2.0 credentials

1. Log in to the SimWorkflow.
2. Navigate to Credentials.
3. Click Create credentials button.
4. Select OAuth 2.0 tab.
5. Select Slack from the Provider dropdown.
6. Enter Slack in the Name field.
7. Paste the Client ID in the Client ID field.
8. Paste the Client Secret in the Client secret field.
9. Enter chat:write to the Scopes field.
10. Click Create credentials button.

We'll use this credentials in the workflow definition when we integrate with Slack to send alerts.

Step 12: Create SimWorkflow Personal Access Token

1. Log in to the SimWorkflow.
2. Navigate to Settings > Personal access tokens.
3. Enter SimWorkflow in the Name field.
4. Enter 30 in the Token expiration in days fields.
5. Click Create personal access token button.
6. Copy the Token text.

Step 13: Create SimWorkflow Bearer token credentials

1. Log in to the SimWorkflow.
2. Navigate to Credentials.
3. Click Create credentials button.
4. Select Bearer token tab.
5. Enter SimWorkflow in the Name field.
6. Paste the Token in the Bearer token field.
7. Click Create credentials button.

We'll use this credentials in the workflow definition when we integrate with SimWorkflow to fetch workflow details.

Step 14: Create SimWorkflow workflow definitions

Step 14.1: Plan error handling workflow definition

We consider the website is down when the website URL we're checking returns a non 2xx response status.

When a website is down, the error handling workflow definition will be started to perform the following tasks:

1. Fetch the failed workflow for the failure state.
2. Then execute the following parallel tasks:
   • Send Email alert.
   • Send SMS alert.
   • Send Slack alert.

Step 14.2: Define error handling workflow definition

1. Log in to the SimWorkflow.

2. Navigate to Workflow definitions.

3. Click Create workflow definition button.

4. Select General tab of the workflow definition.

5. Enter Error handling to the Name field.

6. Click HTTP Task to add a system task and name it Fetch WF details.

7. Connect the Start task to the Fetch WF details task.

8. Click Fetch WF details task and select Input Parameters tab.

9. Enter the following JSON object to the Input parameters field:

   {
     "failureWorkflow": "${workflow.input['swf:failureWorkflow']}"
   }
   

   The system will reference the "swf:failureWorkflow" field from the workflow input to the "failureWorkflow" field.

10. Click Fetch WF details task and select Configuration tab.

11. Select SimWorkflow (Bearer token) for Credentials field.

12. Enter the following JSON object to the HTTP request field:

    {
      "url": "https://api.simworkflow.com/workflow-definitions/${failureWorkflow['swf:workflowDefinitionId']}",
      "method": "GET",
      "headers": {
        "Accept": "application/json",
        "Content-Type": "application/json"
      }
    }
    

    The HTTP request configuration will call the SimWorkflow API to retrieve the workflow definition of the failed workflow.

13. Click Fetch WF details task and select Routing tab.

14. Check Take all routes for Take routes of field.

15. Click Email Task to add a system task and name it Email.

16. Connect the Fetch WF details task to the Email task.

17. Click Email task and select Input Parameters tab.

18. Enter the following JSON object to the Input parameters field:

    {
      "text": "! Workflow '${['Fetch WF details'].output.body.name}' <https://www.simworkflow.com/workflows/${workflow.input['swf:failureWorkflow']['swf:workflowId']}> failed due to: ${workflow.input['swf:failureWorkflow']['swf:cause']}",
      "subject": "Workflow ${['Fetch WF details'].output.body.name} failed",
      "fromName": "SimWorkflow",
      "toAddress": "${['swf:variables'].emailAddress}"
    }
    

19. Click Email task and select Configuration tab.

20. Enter the following JSON object to the Email field:

    {
      "text": "${text}",
      "subject": "${subject}",
      "fromName": "${fromName}",
      "toAddresses": [
        "${toAddress}"
      ]
    }
    

21. Click HTTP Task to add a system task and name it Slack.

22. Connect the Start task to the Slack task.

23. Click Slack task and select Input Parameters tab.

24. Enter the following JSON object to the Input parameters field:

    {
      "body": {
        "text": "Workflow *${['Fetch WF details'].output.body.name}* failed due to `${workflow.input['swf:failureWorkflow']['swf:cause']}`",
        "channel": "${['swf:variables'].slackChannelId}"
      }
    }
    

25. Click Slack task and select Configuration tab.

26. Select Slack (OAuth 2.0) for Credentials field.

27. Enter the following JSON object to the HTTP request field:

    {
      "url": "https://slack.com/api/chat.postMessage",
      "body": "${body}",
      "method": "POST",
      "headers": {
        "Accept": "application/json",
        "Content-Type": "application/json"
      }
    }
    

    The HTTP request configuration will call the Slack API to post the alert message to the Slack channel.

28. Click HTTP Task to add a system task and name it SMS.

29. Connect the Start task to the SMS task.

30. Click SMS task and select Input Parameters tab.

31. Enter the following JSON object to the Input parameters field:

    {
      "message": "Workflow '${['Fetch WF details'].output.body.name}' failed due to: ${workflow.input['swf:failureWorkflow']['swf:cause']}",
      "mobileNumber": "${['swf:variables'].mobileNumber}",
      "senderId": "SimWorkflow",
      "awsRegion": "${['swf:variables'].awsRegion}"
    }
    

32. Click SMS task and select Configuration tab.

33. Select Amazon SNS (AWS) for Credentials field.

34. Enter the following JSON object to the HTTP request field:

    {
      "url": "https://sns.${awsRegion}.amazonaws.com/?Action=Publish&Message=${jsonata:$encodeUrl(message)}&PhoneNumber=${jsonata:$encodeUrl(mobileNumber)}&MessageAttributes.entry.1.Name=AWS.SNS.SMS.SenderID&MessageAttributes.entry.1.Value.DataType=String&MessageAttributes.entry.1.Value.StringValue=${jsonata:$encodeUrl(senderId)}&Version=2010-03-31&AUTHPARAMS",
      "method": "GET"
    }
    

    The HTTP request configuration will call the AWS API to publish the SMS message to the mobile phone number.

35. Click End Task to add a system task and name it End.

36. Connect the Email task to the End task.

37. Connect the Slack task to the End task.

38. Connect the SMS task to the End task.

39. Click End task and select Routing tab.

40. Check Collector task checkbox.

41. Click Save button.

42. Toggle the Enable checkbox to enable the workflow definition.

Use this workflow definition

Step 14.3: Define monitor website workflow definition

1. Log in to the SimWorkflow.

2. Navigate to Workflow definitions.

3. Click Create workflow definition button.

4. Select General tab of the workflow definition.

5. Enter Monitor website to the Name field.

6. Select Error Handling tab of the workflow definition.

7. Select Monitor website error handling to the Workflow definition field.

8. Click HTTP Task to add a system task and name it Ping website.

9. Connect the Start task to the Ping website task.

10. Click Ping website task and select Input Parameters tab.

11. Enter the following JSON object to the Input parameters field:

    {
      "checkEndpoint": "${['swf:variables'].urlToCheck}"
    }
    

12. Click Ping website task and select Configuration tab.

13. Enter the following JSON object to the HTTP request field:

    {
      "url": "${checkEndpoint}",
      "method": "GET"
    }
    

    The HTTP request configuration will call the checkEndpoint. The workflow will complete if the endpoints return a 2xx response status, otherwise the workflow will fail.

14. Click Save button.

15. Toggle the Enable checkbox to enable the workflow definition.

Use this workflow definition

Step 15: Define variables

1. Log in to the SimWorkflow.

2. Navigate to Workflow definitions.

3. Click Variables menu item from the three dots (more options) menu of the Monitor website workflow definition.

Step 15.1: URL to check

1. Enter urlToCheck in the Variable key field.

2. Enter the full URL monitor in the Variable value field.

3. Click Save variable button.

Step 15.2: Email address

1. Enter emailAddress in the Variable key field.

2. Enter the email address to receive the notification in the Variable value field.

3. Click Save variable button.

Step 15.3: Mobile phone number

1. Enter mobileNumber in the Variable key field.

2. Enter the mobile number to receive the SMS message in the Variable value field.

3. Click Save variable button.

Step 15.4: AWS region

1. Enter awsRegion to the Variable key field.

2. Enter AWS region to the Variable value field.

3. Click Save variable button.

Step 16: Run the workflow definition

1. Log in to the SimWorkflow.
2. Navigate to Workflow definitions.
3. Click Run menu item from the three dots (more options) menu of the Monitor website workflow definition.
4. The system checks the website and the workflow Completed.
5. If the check fails, the error handling workflow definition will be started to send email alert, SMS alert, and Slack alert.

Step 17: Define the schedule with cron expression

1. Log in to the SimWorkflow.

2. Navigate to Workflow definitions.

3. Click Schedule trigger menu item from the three dots (more options) menu of the Monitor website workflow definition.

4. Turn on Schedule trigger on field.

5. Select a user for User to start the workflow as field.

6. Enter 0 */2 * ? * * to the Schedule cron expression field. This will execute the check every two minutes.

7. Click Save schedule trigger button.

Summary

You've now successfully completed all the steps necessary to define a workflow definition to monitor a website for uptime. You've learned how to integrate with a third party APIs with different authentication methods: AWS, OAuth 2.0, Bearer token. As a result, you are able to have an automated process to check a website and send alerts when the website is down.