Troubleshooting CAEP Hub

This document describes the steps to troubleshoot CAEP Hub in your environment with some common issues that new users may face, and how to navigate them.

Basic Troubleshooting

Basic Troubleshooting in CAEP Hub is consistent with other parts of the SGNL Product. CAEP Hub has dedicated logging channels for understanding Rules and Actions that may have completed, failed, or had an error returned. These logs are available from the Logging section in the Nav, within CAEP Hub.

Oftentimes, errors are encounted because one or more Actions is failing, so it’s often good to start your troubleshooting in the Actions Failed section of CAEP Hub Logging. Action Failed logs will include details of the Rule that triggered the Action, the Action Name, as well as a message as to why the failure is occurring. If you’re seeing the same Action fail repeatedly, a good first course of action may be to disable the Rule until you understand why the Action is failing.

An Action Failed logline has a number of useful properties (a subset are included below):

actionIndex: 0
actionType: SlackRevokeSession-1.0.0
address: https://api.slack.com
error: provided auth token is missing required "Bearer " prefix
ruleDisplayName: Revoke Sessions following Incident
ruleId: 30dbf5a2-7331-4d05-a299-1a205efc9918
viewId: {"OktaUser.id":"00u4uuhxg6zEaMabV1d7","ServiceNowITSMChangeRequest.sysId":"5167dfcac3a492103e3f7fd9d001312d","ServiceNowITSMConfigurationItem.id":"b92ad6d4c3374a503e3f7fd9d00131f0","ServiceNowITSMUser.sysId":"5b00ab008737c910793a97983cbb354a"}

From this logline, I can see the very first Action in the Rule to Revoke Sessions is failing – it’s a Slack Session Revoke Action and the error provides a pretty good indication of what’s going on. I should go and update the Protected System Action that is using Bearer Authentication to include a Bearer prefix (or some other prefix) before the token.

In other cases, the error might include a HTTP Status Code. If you see a 4xx HTTP status code, some helpful tips to check include:

  • 400 - Ensure that all of the fields you need have been prefilled with valid data or valid/populated parameters from the SGNL Graph
  • 401 - Ensure that you have authentication configured, and that the credentials you have provided are valid and able to authenticate to the target system – in some cases, this may also be a permission issue, see below
  • 403 - Ensure that you have all the right permissions to perform the necessary action. This may include requesting additional scopes from an Authorization Server, or the inclusion of additional scopes in the SGNL Protected System configuration.
  • 404 - Ensure that you have the right address populated in the Protected System configuration for the action, or if overriding the address in a given action, ensure that both the static and dynamic (i.e. parameter-based) data is correct

More Advanced Troubleshooting

A Rule isn’t starting any action(s)

  1. Verify your Rule is enabled
  2. Check to see whether an action has recently fired for the object with that Unique Identifer, SGNL attempts to prevent firing duplicate rules/actions for the same entity (or set of entities) in the graph – if you’re just testing, attempt to try this action on an object with a new unique identifier
  3. Verify that your trigger is matching at least one node, or set of nodes in the graph. The best method for checking this is using SGNL’s DataLens feature – traverse the nodes in Data Lens that you expect your Trigger to be traversing and look for any issues – remember that conditions are sensitive to case, spacing, and formatting

A Rule is firing actions repeatedly

  1. SGNL automatically retries failing actions, if you look in the SGNL Action Failed Logs, do you see multiple failed actions? If so, it’s likely a good option to disable your rule and investigate the cause of your failing action
  2. You may have multiple matches in the graph, for the Trigger that you have configured, recall that SGNL uses the uniqueId of every node that’s added to build a compound Id for the result set, what this means is that every permutation of the trigger will trigger the same set of actions – as an example, using the Complex Trigger of Entra Users, ServiceNow Users, and ServiceNow Changes
    • If you have one Entra ID User (ID: 1) that has a SameAs relationship with two distinct ServiceNow Users (IDs: 2 and 3)
    • Those two ServiceNow Users are assigned to two changes each (IDs: 4,5 and 6,7) which have active set to false
    • You’ll have 4 distinct permutations of that trigger, i.e.
      • 1-2-4
      • 1-2-5
      • 1-3-6
      • 1-3-7
    • This will mean that any Rule that contains this trigger will fire all included Actions 4 times (one for each permutation). If that’s not the intention, you may want to look at a the nodes and conditions in your trigger

A Rule is completing but has an error condition

  1. This most commonly occurs when one of the parameters you are using in an action does not have a value. Check your Action Parameters and compare them with the data in Data Lens, do all of your expected attributes have the values you might expect (i.e. are not null)

My Actions are giving unpredictable results

  1. The best position to start troubleshooting this issue from is the CAEP Hub Insights page (or the SGNL Logs). Here we log the unique identifiers for each of the objects that were matched in the trigger. By simply clicking one of those identifiers, we’ll take you to Data Lens to inspect the object to look for any anomalies, or issues that you may not have expected.