Risk Assessments

This page shows how to work with FlightRisk risk assessments.

Risk assessments can be viewed inside FlightRisk, or returned from the API in a static form for display outside FlightRisk.

Task	Purpose
Actions
Execute	Execute a risk assessment and receive the return in a variety of formats.
Create URL	Create a Single Sign On (SSO) URL that points to an existing risk assessment.
Obtaining Status	Allows the status of multiple risk assessments to be queried at once.
Data Structures
Planning Information	The input data structure required for executing a risk assessment.
Execution Results	The output data structure generated after successful execution.

/RiskAssessments/Execute

HTTP PUT Impersonated User Accounts

Uses the planning information provided to execute a risk assessment.

Risk assessments must always be executed as an impersonated user account. This allows the risk assessment to be associated with a specific person, and ensures that any generated URLs contain security information appropriate to that person.

See Impersonating a User Account

Input

Field	Type	Constraints	Detail
planningInfo	Object	Required	See Planning Information
packageFormat	String		An HTML copy of the risk assessment (a "package") can optionally be returned, and the contents of this package will contain data such as weather, NOTAMs, airfield information, fatigue scores, etc. FlightRisk administrators can customize the exact contents of the package on a domain-by-domain basis. Accepted Values (Omit) - don't return any additional output. `html` - return a standalone representation of the output as HTML.
packageTemplateType	String	May be Required	If `packageFormat` is specified, this value must be used to specify the contents of the package. FlightRisk allows customization of risk assessment output. Each domain can customize a summary and detail version of the output. If no customizations are present, FlightRisk will use its default version of the template. Accepted Values `summary` - use the domain's template for a summary report. `detail` - use the domain's template for a detailed report
isImplicitRequest	Boolean		Marks execution as implicit. This flag is used for risk assessments which are run automatically as part of another process, and do not involve a user at all. Implicit risk assessments cannot return a URL or package. Implicit assessments are not guaranteed to run, as different domains can disable this feature. Implicit assessments will also generate fewer notifications.
urlType	String		This method can optionally generate a URL to the risk assessment. Accepted Values (Omit) - Don't create a URL. `open` - link to a page that displays the risk assessment. `execute` - link to a page intended to execute the risk assessment.

Sample Payload

        var payload = {
            packageFormat: "html",
            packageTemplateType: "summary",
            urlType: "execute",
            planningInfo: {
                purpose: "flightPlanning",
                tailId: "callers_tail_ID_12345",
                rulesetId: 5,
                flightType: "ifr",
                airfields: [{
                    code: "kbos",
                    timeOfInterest: "2019-05-23T16:00:00.000Z",
                    designation: "departure"
                },
                {
                    code: "kjfk",
                    timeOfInterest: "2019-05-23T19:30:00.000Z",
                    designation: "arrival"
                }],
                crew: [{
                    accountId: "callers_account_ID_1",
                    position: "pilotInCommand"
                },
                {
                    accountId: "callers_account_ID_2",
                    position: "secondInCommand"
                }]
            }
        };

Output

The executionResults property will always contain the number and detail of advisories that were triggered during execution. If a package and/or single sign on (SSO) link have been requested, they will also be included in the response.

Field Type Description

riskAssessmentId

Integer

The identity of the risk assessment record used in the execution. This ID may be for a new risk assessment that was created, or an existing risk assessment that was automatically picked by FlightRisk based on similar planning information.

This is FlightRisk's ID for the assessment and can be stored by the caller to refer to it later.

executionResults

Object

Aggregated and detail data about execution, including all advisories that were triggered.

See Execution Results

If URL Requested

url String URL for the risk assessment. The URL destination may vary depending on the urlType specified. This URL will contain specific security information for the account requesting it and should be treated carefully.

If Package Requested

package

Object

Field

Type

Detail

fileName

String

A generated file name for the package.

data

String

The base-64 encoded contents of the file.

supportingFiles

Array

Field	Type	Detail
data	String	The base-64 encoded contents of the file.

Sample Response

This example shows a response where no package or URL has been requested, and two advisories have been triggered. One of the advisories pertains to a specific airfield.

    {
      "riskAssessmentId": 123456,
      "package": null,
      "url": null,
      "executionResults": {
        "totalQueryCount": 4558,
        "stopCount": 0,
        "yieldCount": 1,
        "infoCount": 0,
        "newStopCount": 0,
        "newYieldCount": 1,
        "newInfoCount": 0,
        "advisories": [
          {
            "title": "135 Icing limitations*'",
            "warningMessage": "Takeoffs may be made with frost under wing (below fuel tanks) if authorized by Administrator.",
            "mitigationMessage": "Ensure aircraft is free of contaminants in accordance with AFM.",
            "severity": "yield",
            "classification": "preflight",
            "classificationCaption": "Pre-Flight",
            "airfield": {
              "id": 67553,
              "code": "KBUF",
              "timeOfInterest": "2020-06-02T14:09:00.000Z",
              "designation": "departure",
              "isAlternate": false
            },
            "crewMember": null
          },
          {
            "title": "91 PIC Flying Time less than 1500 hrs",
            "warningMessage": "PIC does not meet crew member experience requirements of 1500 hours total flight time.",
            "mitigationMessage": "PIC has logged 1254 hours. Administrator may authorize deviations.",
            "severity": "stop",
            "classification": "pilot",
            "classificationCaption": "Pilot",
            "airfield": null,
            "crewMember": {
              "id": 98400,
              "name": "Jane Smith"
            }
          }
        ]
      }
    }

/RiskAssessments/Url

HTTP POST Impersonated User Accounts

Creates a URL with security information in it for the user impersonated in the call.

Input

Field	Type	Constraints	Detail
riskAssessmentId	Integer	Required	FlightRisk's ID for the risk assessment. This can be obtained from a prior execution or from requesting the status of a batch of risk assessments.
urlType	String	Required	This method returns a URL that links to the risk assessment. This property specifies where the URL should go. Valid values: `open` - link to a page that displays the risk assessment. `execute` - link to a page intended to execute the risk assessment.

Sample Payload

        var payload = {
            id: 1234,
            urlType: "execute"
        };

Output

Field	Type	Description
url	String	URL for the risk assessment. The URL destination may vary depending on the `urlType` specified. This URL will contain specific security information for the user account being impersonated and it should be treated carefully.

/RiskAssessments/Status

HTTP POST Service Accounts

Locates multiple risk assessments and returns data about their most recent execution (if any).

Risk Assessments are retrieved by leg ID. It does not matter where the assessment originated from; if there is one associated with the leg, information about it will be returned.

Note that unlike execution, obtaining the status of a risk assessment does not require or allow impersonation.

Input

Field	Type	Constraints	Detail
legIds	Array of Mapped IDs	Required	Between 1-50 IDs can be provided in a single call.

Sample Payload

        var payload = {
            legIds: ["800", "801", "802"]
        };

Output

The return may contain a mix of success and failure statuses due to whether a risk assessment was located. Check the status field for each item in the operations array.

As long as the request is authorized and correctly-formed, the response code will still be HTTP 200 even if some/all of the operations fail to locate a risk assessment.

Field Type Description

operations

Array

An array containing one entry per legId submitted.

Field Type Description

operationId String Corresponds to the leg ID for which a status was requested. This is the caller's Mapped ID for the leg (not to be confused with FlightRisk's ID for the leg).

status

String

Possible Values

ok: a risk assessment was located and further information is included in the results.
legNotFound: the leg requested wasn't found. Check for a missing sync with FlightRisk.
noRiskAssessmentForLeg: the leg was found, but wasn't associated with a risk assessment. If data is desired, one should be executed.

If status is ok

riskAssessmentId Integer Contains FlightRisk's ID for the risk assessment. This ID can be used to request a URL to the risk assessment.

lastExecutionDate Date The date of the most recent execution.

lastExecutedBy String The name of the user who last executed the risk assessment.

lastExecutionSource

Object

Sources can initiate actions (like execution) and/or provide data. This property can be used to display or determine the origin of the last execution.

Field	Type	Description
name	String	The name of the source. This value can be treated as a unique and unchanging identifier.
caption	String	The friendly name of the source, suitable for display.

advisories

Object

Field	Type	Description
stopCount	Integer	The current number of advisories with a severity level of `stop`.
yieldCount	Integer	The current number of advisories with a severity level of `yield`.
infoCount	Integer	The current number of advisories with a severity level of `info`.

acknowledgement

Object

Field	Type	Description
isRequired	Boolean	`true` if acknowledgement is currently required for the assessment, otherwise `false`.

fatigue

Object

Field	Type	Description
wasAnalyzed	Boolean	`true` if fatigue was analyzed the last time the assessment was run, otherwise `false`.
If `wasAnalyzed` is `true`
worstDepartureScore	Float	Contains the numeric score of the most severe departure rating across all crew members.
worstDepartureRating	String	Contains the classification of the most severe departure rating across all crew members. `warning`: most severe `caution` `normal`: least severe
worstArrivalScore	Float	Contains the numeric score of the most severe arrival rating across all crew members and any alternates.
worstArrivalRating	String	Contains the classification of the most severe arrival rating across all crew members and any alternates. `warning`: most severe `caution` `normal`: least severe

Sample Results

This example shows the results for three legs. One leg has a risk assessment, and its data is returned. One leg could not be found by its mapped ID. The third leg was found, but no assessment had been run for it yet, or the assessment was deleted from within FlightRisk. If an assessment for the leg was desired, it could be executed.


{
  "operations": [
    {
      "operationId": "800",
      "status": "ok",
      "riskAssessmentId": 12345,
      "lastExecutionDate": "2020-08-18T20:58:34.343Z",
      "lastExecutedBy": "Sally O'Brien",
      "lastExecutionSource": {
        "name": "ArincDirect",
        "caption": "ARINC Direct"
      },
      "fatigue": {
        "wasAnalyzed": true,
        "worstDepartureScore": 4.8,
        "worstDepartureRating": "normal",
        "worstArrivalScore": 6.7,
        "worstArrivalRating": "caution"
      },
      "advisories": {
        "stopCount": 0,
        "yieldCount": 3
      },
      "acknowledgement": {
        "isRequired": false
      }
    },
    {
      "operationId": "801",
      "status": "legNotFound"
    },
    {
      "operationId": "802",
      "status": "noRiskAssessmentForLeg"
    }
  ]
}

Input and Output Structures

Planning Information

Information about the leg that should be assessed.

Field Type Constraints Detail

legId Mapped ID If present, the risk assessment will be associated to the leg. Otherwise, FlightRisk will attempt to automatically match the risk assessment to a similar leg.

tailId Mapped ID Required

flightType

String

Required

Accepted Values

ifr
vfr
yfr
zfr

purpose

String

Required

FlightRisk uses the purpose field to improve the accuracy of aggregated safety analytics for a domain.

Accepted Values

quoting - the assessment is a "what if" analysis and doesn't represent a scheduled leg.
flightPlanning - the leg is scheduled, though the planning information may still change.
filing - a flight plan has been, or is about to be, filed for the leg and the planning information is unlikely to change.

rulesetId

Integer

Required

FlightRisk's ID for a ruleset obtained by calling the Rulesets API. This is the primary ruleset to be used in evaluating the planning information; FlightRisk will automatically add other rulesets as needed.

Each domain may have a customized list of rulesets available to them.

flightPlanNumber String 50 An informational flight plan number/ID that may be associated with the risk assessment.

specialCircumstanceIds Integer Array An array of special circumstance IDs; candidate IDs are obtained by calling the Rulesets API.

airfields

Array

Required

Field	Type	Constraints	Detail
code	Airfield Code	Required
timeOfInterest	Date	Required
designation	String	Required	Valid values: `departure` `arrival`
isAlternate	Boolean		Set to true to designate the airfield as an alternate.

crew

Array

Field Type Constraints Detail

accountId Mapped ID Recommended The caller's ID for the crew member. This value is required unless adHocName is provided.

adHocName String 100 If no account ID is available for the crew member, this name may be provided instead.

position

String

Accepted Values

pilotInCommand
secondInCommand
flightAttendant
flightEngineer
otherCabinCrew

Execution Results

Field Type Detail

stopCount Integer The number of advisories with a severity level of stop.

yieldCount Integer The number of advisories with a severity level of yield.

infoCount Integer The number of advisories with a severity level of info.

newStopCount Integer The number of new advisories with a severity level of stop.

newYieldCount Integer The number of new advisories with a severity level of yield.

newInfoCount Integer The number of new advisories with a severity level of info.

advisories

Array

Field Type Detail

title String The title of the advisory.

warningMessage String The advisory's warning.

mitigationMessage String The action recommended to mitigate the condition(s) matched by the advisory.

severity

String

Possible Values

stop
yield
information
system

classification

String

Possible Values

general
pilot
preFlight
taxiOut
departure
enroute
arrival
approach
landing
taxiIn

classificationCaption String A friendly name of the advisory's classification, suitable for display.

reference

object

Field Type Detail

regulationsAndSops String Array The regulations/standard operating procedure(s) from which this advisory is derived.

document

Object

If a document has been attached to the advisory, the following properties will be populated. Otherwise it will be null.

Field	Type	Detail
title	String	The title of the document.
url	String	The URL of the document. This URL does not contain any security information, so it may safely be displayed where multiple users may see/use it.

airfield

Object

If the advisory is airfield-specific, this property will contain basic information about the airfield so that advisories can be grouped by airfield if desired. If the advisory does not pertain to an airfield, this property will be null.

Field	Type	Detail
id	Integer	A value that can be used to easily differentiate between airfields, even if they have the same code due to taking off and landing at the same field such as might occur during a flight demonstrating an aircraft.
code	Airfield Code
timeOfInterest	Date
designation	String	`departure` `arrival`
isAlternate	Boolean	Specifies whether the airfield is an alternate.

crewMember

Object

If the advisory pertains to a crew member, this property will contain basic information about them so that advisories can be grouped by crew member if desired. If the advisory does not pertain to a crew member, this property will be null.

Field	Type	Detail
id	integer	A value that can be used to easily differentiate between crew members without relying on a name comparison.
name	String

Sample

This example shows a execution result structure with two advisories. One advisory pertains to an airfield, the other to a pilot.


    {
      "totalQueryCount": 4558,
      "stopCount": 0,
      "yieldCount": 1,
      "infoCount": 0,
      "newStopCount": 0,
      "newYieldCount": 1,
      "newInfoCount": 0,
      "advisories": [
        {
          "title": "135 Icing Limitations",
          "warningMessage": "Takeoffs may be made with frost under wing (below fuel tanks) if authorized by Administrator.",
          "mitigationMessage": "Ensure aircraft is free of contaminants in accordance with AFM.",
          "severity": "yield",
          "classification": "preflight",
          "classificationCaption": "Pre-Flight",
          "reference": {
            "regulationsAndSops": [
              "FAR 135.123456"
            ],
            "document": {
              "title": "135 Sample Document",
              "url": "https://flightrisk.vocus.aero/Documents/File/12345"
            }
          },
          "airfield": {
            "id": 67553,
            "code": "KBUF",
            "timeOfInterest": "2020-06-02T14:09:00.000Z",
            "designation": "departure",
            "isAlternate": false
          },
          "crewMember": null
        },
        {
          "title": "91 PIC Flying Time less than 1500 hrs",
          "warningMessage": "PIC does not meet crew member experience requirements of 1500 hours total flight time.",
          "mitigationMessage": "PIC has logged 1254 hours. Administrator may authorize deviations.",
          "severity": "stop",
          "classification": "pilot",
          "classificationCaption": "Pilot",
          "reference": {
            "regulationsAndSops": [
              "FAR 91.123456",
              "Sample Company SOP"
            ],
            "document": {
              "title": "91 Sample Document",
              "url": "https://flightrisk.vocus.aero/Documents/File/12345"
            }
          },
          "airfield": null,
          "crewMember": {
            "id": 98400,
            "name": "Jane Smith"
          }
        }
      ]
    }

API Version 14.1.9203.25168