Using Web Services to Provide an Outage Dashboard/Status Page in the Knowledge Base

This guide will help Administrators to provide information on ticket outages to the KB via workflow. The user must have the following settings enabled within the Security Role: Global Admin or a user with KB Create/Publish rights AND Ticketing App Admin Rights with Web Service calling resources in place. 

Overview:

It is critical to provide your organization information about outages.  Integrating this action with the normal ticketing processes can be an effective way to automate the provision of this information.  If you are looking for a simple way to provide this information with reports and public desktops you can read more about that here: Using Reporting and Desktops to Provide a Status Page. 

The downfall of using a public desktop is that the content is outside of authentication and cannot be restricted with by permissions.  Using this process is more complex but it does allow for controlling the content as it is subject to whatever permissions and visibility you setup in the Knowledge Base.

The process outlined below will cover some of the data you will need to provide in order to allow the Web Service API call to succeed and will explain the actual API call construction and how to apply it to tickets with workflow.  The images directly below show how this might look in your environment if you follow this guide.

Here is an example of the Knowledge Base Category.  The left side shows no outages while the right shows 1 active outage:

This is an example of the articles content during the active outage: 

Here is the same article after the issue is resolved:

How to Provide Outage Info Through Knowledge Base:

Before you build the API calls and the workflow you will need to ensure a few pieces of data that are specifically used in this process:

Prerequisites:

  1. First you will need to decide what kind of tickets you plan to pull this data from.  The most straight forward way to manage this would be to create a form (likely a problem form to align with ITIL definitions and processes) specifically for outages.  Whatever tickets you want to run this process on, you will want to make sure it has 2 specific attributes on the related form:
    1. You will need to make sure that you place a dropdown selector attribute on the form populated with all the of the high level systems/categories you will report outages against. (i.e. Email, Internet Services, Phone Services, HRM, etc.) 
    2. You will want to create a text box attribute called something like "Anticipated Restoration".  This is where you will enter the date/time for restoration of the service. This needs to be a text box for formatting reasons in the API call. 
  2. You will need to have the ability to create Web Service Methods in your ticketing app.  If you are new to this process you will want to start with this content: Getting Started with Workflow Web Services.
  3. You will need to collect several pieces of data
    1. Decide what group will "own" the KB articles; collect the Group ID number; alternatively you can use a single User but note that the API calls in this example have specific data directed at a group ownership and would need to be modified
    2. Find the Client Portal App ID number.  This should be the client portal that the KB you are going to post to resides in; can be found at TDAdmin> Applications

 

Building the Knowledge Base Content:

  1. Navigate to the Client Portal and open the Knowledge Base
  2. Create a Category called something like "Outage Dashboard"
  3. Document the Category ID number for use later in the API calls
  4. Create a KB article for each section you plan to report on; this should be the same list from the prerequisite step 1.1 above
    • These articles should carry the standard name for when the service is fully operational; such as "Email - Operational"
    • The body can have a place holder for the data such as "Service has no active outages"
    • Approve and Publish the Articles so they are live and able to be worked with
  5. Document the article ID from each article and save that information for the API call building in the next section

 

Building the API Calls for Outage Posting:

  1. Navigate to TDAdmin> Applications> Your Ticketing Application> Workflow Web Services> Web Service Methods
  2. Click +New to create a new method
  3. Name the method something like Outage Report - Name of your service; replace the italics text with one of the names of your services from the drop down; use a standardized naming to keep things easy to identify as you build
  4. Choose your Web Service Provider in the drop down
  5. Select the call method of PUT from the green drop down
  6. Add the call URL of: https://yourdomainname.teamdynamix.com/TDWebApi/api/{appID}/knowledgebase/{articleID}
    • replace the "yourdomainname.teamdynamix.com" with your root BE domain name
    • replace the {appID} with the client portal ID number
    • replace the {articleID} with the article ID number from the associated KB aricle that matches what you put in the method name
      • ex. if your method name is "Outage Report - Email Services"; then put the article ID from the Email article created in the Building the Knowledge Base Content: Step 4 above
  7. In the Key box enter: Content-Type 
  8. In the Value box enter: application/json
  9. Now click the green +Add button
  10.  Navigate to the Parameters tab
  11. Enter the following parameters {Name-Data Type-Source-Source Property} 
    • ETA - String - From Ticket - {Choose the custom attribute for anticipated restoration time from Prerequisites step 1.2}   ; Click the green +Add 
    • Description - String - From Ticket - Description   ; Click the green +Add
  12. Navigate to the </> Body tab
  13. Enter the following into the body:
    • {
      "IsRichHtml":true,
      "Subject":"replace with your service name for this method - Outage - ETA:{{ETA}}",
      "Status":"3",
      "Order":"0.5",
      "OwningGroupID":replace with your owning group id number,
      "IsPublished":true,
      "CategoryID":replace with your KB Category id number,
      "Body":"This service is currently experiencing an outage.  The IT team is working to resolve this issue.  Current anticipated restoration time (if available) is: {{ETA}}.  Please check back here for further updates. </br></br> Details: </br></br>
      {{Description}}",
      }
      • EXAMPLE of a completed call body:
        {
        "IsRichHtml":true,
        "Subject":"Email - Outage - ETA:{{ETA}}",
        "Status":"3",
        "Order":"0.5",
        "OwningGroupID":1424,
        "IsPublished":true,
        "CategoryID":2615,
        "Body":"This service is currently experiencing an outage.  The IT team is working to resolve this issue.  Current anticipated restoration time (if available) is: {{ETA}}.  Please check back here for further updates. </br></br> Details: </br></br>
        {{Description}}",
        }
  14. Navigate to the Authentication tab
  15. Select your Auth Account from the dropdown
  16. Save the Method
  17. Test the method at this point by clicking the Test Request button and entering some data for the outagedate parameter and the Description parameter in the Test Request window
    • If the call succeeds you can navigate to the associated article in the KB and see the changes made to the articles title, order, and content
  18. Repeat steps 1 through 17 for each of your services you are going to report on;  the same quantity and names as your KB articles that you created
    • TIP: It can be very helpful to copy the content from your first created call here as many of the elements are the same from call to call 

 

Building the API Calls for Outage Restoration:

  1. Navigate to TDAdmin> Applications> Your Ticketing Application> Workflow Web Services> Web Service Methods
  2. Click +New to create a new method
  3. Name the method something like Outage Restore - Name of your service; replace the italics text with one of the names of your services from the drop down; use a standardized naming to keep things easy to identify as you build; should look very similar to the first calls built for the outage posting
  4. Choose your Web Service Provider in the drop down
  5. Select the call method of PUT from the green drop down
  6. Add the call URL of: https://yourdomainname.teamdynamix.com/TDWebApi/api/{appID}/knowledgebase/{articleID}
    • replace the "yourdomainname.teamdynamix.com" with your root BE domain name
    • replace the {appID} with the client portal ID number
    • replace the {articleID} with the article ID number from the associated KB aricle that matches what you put in the method name
      • ex. if your method name is "Outage Restore - Email Services"; then put the article ID from the Email article created in the Building the Knowledge Base Content: Step 4 above
  7. In the Key box enter: Content-Type 
  8. In the Value box enter: application/json
  9. Now click the green +Add button
  10.  Navigate to the Parameters tab
  11. Enter the following parameters {Name-Data Type-Source-Source Property} 
    • outagedate - String - From Ticket - {Choose the custom attribute for anticipated restoration time from Prerequisites step 1.2}   ; Click the green +Add 
    • Description - String - From Ticket - Description   ; Click the green +Add
  12. Navigate to the </> Body tab
  13. Enter the following into the body:
    • {
      "IsRichHtml":true,
      "Subject":"replace with your service name for this method - Operational",
      "Status":"3",
      "Order":"1",
      "OwningGroupID":replace with your owning group id number,
      "IsPublished":true,
      "CategoryID":replace with your KB Category id number,
      "Body":"This service is currently operational with no active outages.</br></br>
      <table>
      <tr>
         <td>Last Outage Date:</td> 
         <td>{{outagedate}}</td>
      </tr>
      <tr>
         <td>Details:</td>
         <td>{{Description}}</td>
      </tr>
      </table>",
      }
      • EXAMPLE of a completed call body:
        {
        "IsRichHtml":true,
        "Subject":"Email - Operational",
        "Status":"3",
        "Order":"1",
        "OwningGroupID":1424,
        "IsPublished":true,
        "CategoryID":2615,
        "Body":"This service is currently operational with no active outages.</br></br>
        <table>
        <tr>
           <td>Last Outage Date:</td> 
           <td>{{outagedate}}</td>
        </tr>
        <tr>
           <td>Details:</td>
           <td>{{Description}}</td>
        </tr>
        </table>",
        }
  14. Navigate to the Authentication tab
  15. Select your Auth Account from the dropdown
  16. Save the Method
  17. Test the method at this point by clicking the Test Request button and entering some data for the ETA parameter and the Description parameter in the Test Request window
    • If the call succeeds you can navigate to the associated article in the KB and see the changes made to the articles title, order, and content
  18. Repeat steps 1 through 17 for each of your services you are going to report on;  the same quantity and names as your KB articles that you created and the number of outage report calls you made in the previous section
    • TIP: It can be very helpful to copy the content from your first created call here as many of the elements are the same from call to call

 

Building the Workflow for KB Outage Reporting:

  1. Navigate to TDAdmin> Applications> Your Ticketing Application> Workflows
  2. Click +New to create a new workflow and give it a name to reflect the purpose
  3. Optionally add a Description or Purpose
  4. Click View Builder to open the builder page
  5. Click New Step 
  6. Name the step "Start" and choose Branch as the type
  7. Click Save, then close the step window
  8. Add Condition Steps:
    1. Click New Step 
    2. Name the Step "replace with your service name Condition" (ex. "Email Condition")
    3. Choose Condition as the type
    4. In the conditions section in the column drop down choose the name of the custom attribute drop down from Prerequisites step 1.1 (the dropdown with all the services listed)
    5. set the operator to "is one of"
    6. Choose the associated value as the service name you used here in step 8.2
    7. Click Save and close the step window
    8. Repeat steps 8.1-8.7 until you have a condition created for each associated service in that dropdown attribute
    9. Organize them so you can see each condition 
    10. Connect the Start branch to each condition
  9. Add Web Service Steps:
    1. Click New Step 
    2. Name the step "replace with your service name Outage" (ex. "Email Outage")
    3. Choose Web Service as the type
    4. Select the Associated Web Service Provider/Method in the dropdown for a method created in the Outage Posting section above (ex. TDWebApi/Outage Report - Email)
    5. Optionally set notifications
    6. Click Save and close the step window
    7. Repeat steps 9.1-9.6 until you have a Web Service created for each associated service; one to match each condition
    8. Organize these steps next to each of their related conditions
    9. Connect the Condition Met on the associated condition to the Web Service (outage) step
  10. Add Choice steps:
    1. Click New Step 
    2. Name the step "replace with your service name Restored" (ex. "Email Restored")
    3. Choose Choice as the type
    4. Select the Associated Responsibility to either Assign to a specific resource or Assign to a Role; if choosing a role you must provide a fallback in case of error
    5. Enter the same text as the name in the choice box (ex. "Email Restored"), or a similar statement such as "Email has been restored"
    6. Click Save and close the step window
    7. Repeat steps 10.1-10.6 until you have a Choice created for each associated service; one to match each Web Service Outage Posting
    8. Organize these steps next to each of their related Web Services
    9. Connect the Success on the associated Web Service step to the related Choice
  11. Add Restoration Web Services:
    1. Click New Step 
    2. Name the step "replace with your service name Restored" (ex. "Email Restored")
    3. Choose Web Service as the type
    4. Select the Associated Web Service Provider/Method in the dropdown for a method created in the Outage Restoration section above (ex. TDWebApi/Outage Restore - Email)
    5. Optionally set notifications
    6. Click Save and close the step window
    7. Repeat steps 11.1-11.6 until you have a Web Service created for each associated service; one to match each Choice
    8. Organize these steps next to each of their related Choice
    9. Connect the Choice value on the associated Choice to the Web Service (restore) step
  12. Add closing Branch steps:
    1. Click New Step 
    2. Name the step "replace with your service name Branch Closure" (ex. "Email Branch Closure")
    3. Choose Branch as the type
    4. Click Save and close the step window
    5. Repeat steps 12.1-12.4 until you have a Branch created for each associated service; one to match each restoration Web Service step
    6. Organize these steps next to each of their related Web Service (restore) step
    7. Connect the Success value on the associated Web Service (restore) step to the associated closure Branch
    8. Also Connect the Condition Not Met on the associated service condition to the related closure Branch
  13. You should now have rows of related steps for each reported service/category containing
    • Condition > Web Service (outage) > Choice > Web Service (restore) > Branch
    • An individual row should look something like this:
    • Note that only the condition step has 2 connector lines going downstream (1 to the web service outage, 1 to branch); the rest only have 1 outgoing line. The branch has 2 INCOMING lines (1 from web service restore, 1 from condition).
  14. Click +New Step 
  15. Name it Collector - All Systems Restored
  16. Click Save and close the step window
  17. Move the collector past the last column of Branches
  18. Connect all the Branch closures Alwasy to the Collector
  19. Connect the Connector Complete to the Approve green ending block
    • All together your workflow may look something like this:Uploaded Image (Thumbnail)
  20. Click the Workflow drop down menu and choose Details
  21. In the Approval Status drop down choose the status you want the ticket to take after the calls are all complete; probably Closed/Resolved
  22. Click Save
  23. Choose File> Save and Check In
  24. Close the builder
  25. Navigate to TDAdmin> Applications> Ticketing Application> Workflows
  26. Click on the workflow you have been building
  27. Select Activate at the top to mark it active

 

Running the Workflow on Tickets:

  1. You can now run this workflow on tickets with the appropriate Attributes attached: Service list drop down AND Anticipated Restoration 
  2. The workflow can be attached to tickets via a Service Settings, Automation rule, or manually on tickets under the Actions dropdown
  3. The workflow will evaluate the ticket to determine which service/category is impacted by the outage (the dropdown selection)
  4. The associated Web Service outage will run changing the KB article title and body to reflect that there is a current outage.  It will also change the order value so it appears at the top of the KB Category
  5. Now that the outage is posted in the KB a choice will appear for the indicated responsibility you setup in the workflow step with a single choice button indicating the service is restored
  6. The responsible party will select the restored button once the service is confirmed as restored
  7. The restore Web Service step will then run changing the KB article name back to operational, setting the sort order back to normal, and adjusting the body of the article to say no current outages and displaying the historical information of the outage that just closed
  8. The workflow will then move to the Approve ending and Close/Resolve the ticket

Pitfalls and Gotchas:

  • The attribute used on the form to select the impacted system/category needs to be a singular selection device NOT a multi-select.  The outage tickets will need to be a single ticket for EACH system/category being reported on.  Making multiple API calls in the same workflow at the same time can lead to errors.
  • The Date/Time attribute for anticipated restoration should be a text box and NOT a Date/Time tool as there are formatting issues when trying to write that kind of data back into the knowledge base article.
  • You can configure this for as many services/categories as desired but increasing the quantity can significantly increase the size of content that must be built; Ideally less than 15.  The fewer the better.  Remember you can put details about the outage into the article body as part of the automated updates to the KB.
  • Remember that you must have a Web Service Provider created and a Web Service Auth Account to be able to create Web Service Methods
  • Copying from the first Method you made to subsequent Methods as you build is a great way to save time but be careful to make sure and adjust the Article ID on each call to make sure the call is directed to the corresponding KB article
100% helpful - 1 review

Details

Article ID: 157806
Created
Thu 3/14/24 4:29 PM
Modified
Thu 3/21/24 1:08 PM