Issue resolution API

The issue resolution API allows for the interaction with alerts, incidents and related artifacts.

Note: The API reference (Swagger) document for the issue resolution API is not interactive and is published for your understanding of the different APIs and schemas available. For more information about how to access these APIs, review the following commands and procedure.
Important: The Concert Operate v1 APIs in this topic are planned for deprecation and replacement by v2 APIs in future releases.

Endpoint URLs

Issue resolution events API

$ROUTE/aiops/api/issue-resolution/v1/events/

Issue resolution alerts API

$ROUTE/aiops/api/issue-resolution/v1/alerts/

Issue resolution incidents API

$ROUTE/aiops/api/issue-resolution/v1/incidents
Incident-state transition rules and restrictions
When you update an incident state manually through the incident management API, some state transitions restrict which additional fields you can modify in the same request. To make sure correct interpretation by the system, follow the rules below.
State transitions that do not allow ownership changes
Some transitions require ownership to remain unchanged. If you include owner or team fields during these transitions, the system interprets the update as an ownership change, which is not allowed.
  1. Transition from inProgress to onHold
    • Do not include owner or team fields.
    • The onHold state indicates the incident is temporarily paused under the existing assignment.
    Correct example:
    {
    "state": "onHold"
}
    Incorrect example (ownership change not allowed):
    {
    "state": "onHold",
    "owner": "user@example.com",
    "team": "AIOps"
}
  2. Transition from Any state to resolved
    • Do not include ownership fields.
    • The current owner completes the resolution, if assigned.
State transitions that require ownership
Some manual transitions require an assignment if the incident is currently unassigned. These transitions must include either owner or team.
Transitions requiring ownership fields:
  • unassigned → assignedToIndividual
  • unassigned → assignedToTeam
  • unassigned → inProgress
Example:
{
    "state": "inProgress",
    "owner": "user@example.com"
}

For more information about utilizing Issue resolution incidents API to enrich an incident by using IBM Tivoli Netcool/Impact policy, see Enrich an incident using policies.

Authentication

The API uses Platform UI (Zen) authentication, so you either need a JWT token or ZenApiKey to be authenticated. The token or key is used to determine whether a user or service ID has access when you use the API.

Accessing the API with cURL

  1. Log in to your cluster and authenticate your admin user credentials for running API commands:

    1. Adjust the project (namespace) for your system:

      NAMESPACE=cp4aiops

    2. Get the admin username and set it as an environment variable by running the following command

      USER=$(oc -n $NAMESPACE get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_username}' | base64 -d)

    3. Get the password for your admin username and set it as an environment variable by running the following command:

      PASS=$(oc -n $NAMESPACE get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_password}' | base64 -d)
    Note: Two methods of authentication are available:

    • JWT Bearer Token

      This token is temporary and lasts about 4 hours.

    • Platform UI (ZenApiKey) API key

      This key remains until deleted.

    For more information about API authentication, see Accessing APIs

  2. Set your authentication.

    • If you are using the Platform UI (ZenApiKey) API key option, encode your admin username and API key with Base64 encoding:

      ZENAPIKEY=$(echo "<username>:<API_key>" | base64 -w 0); echo $ZENAPIKEY

    • If you are using the JWT Bearer Token option, set the token as an environment variable. The following command uses variables that are set in the previous step:

      TOKEN=$(curl -k -X POST https://$ROUTE/icp4d-api/v1/authorize -H "Content-Type: application/json" -d "{\"username\": \"$USER\",\"password\": \"$PASS\"}" 2>/dev/null|awk -F'"' '{print $(NF-1)}')

  3. Run a command to access the API. For example, the following command uses cURL to access the issue resolution alerts API to load alert data:

    • By using the route and the Platform UI (ZenApiKey) API key option:

      curl -k -v -X POST "https://${ROUTE}/aiops/api/issue-resolution/v1/alerts/" --header "Content-Type: application/json" --header "Authorization: ZenApiKey ${ZENAPIKEY}" --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' --data @<FILEPATH/FILE>.json

      Where <FILEPATH/FILE> is the full path to the JSON file that includes your sample alert data to load.

    • By using the route and the JWT Bearer Token option:

      curl -k -v -X POST "https://${ROUTE}/aiops/api/issue-resolution/v1/alerts/" --header "Content-Type: application/json" --header "Authorization: Bearer ${TOKEN}" --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' --data @<FILEPATH/FILE>.json

      Where <FILEPATH/FILE> is the full path to the JSON file that includes your sample alert data to load.