Retrieve Work Unit Summary Content Web Service

Use the Retrieve Work Unit Summary Content Web Service to obtain details on the contents or check the status and progress of your released work unit and retrieve filing validation errors and/or warnings that occurred. Additionally, you can retrieve justifications associated to the work unit.

Request

Your request to the Retrieve Work Unit Summary Content Web Service must provide a valid OAuth access token and a userId in the header. See OAuth Access Tokens and Authentication for more information. You must also specify at least one search criteria parameter in the request body.

Requests can be made by specifying at least one of the following search criteria parameters in the URL query string:

  • Work Unit ID, or
  • Work Unit Name, or
  • Work Unit Name and Work Unit Create Date

Users can also retrieve their partner work units by specifying either the Work Unit ID or the combination of Work Unit Name, Work Unit Create Date, and the Partner Organization Code in the request. If date is not provided, today's date will be applied. Partner work units will be retrieved only if partnerOrgCode is provided in the request. If the non-owning work unit carrier actor has no Tier 2 access with the work unit owner, the actor cannot view the work unit.

Users can specify in the request the option to retrieve filing validation errors and/or warnings that may have occurred during the release, test release or scheduled released of the work unit. If filing validation errors and/or warnings exist, the API response will include a sample of each unique error and/or warning. This feature provides users further details on the state of their work unit to assist with auditing and troubleshooting.

retrieveFilingErrors is an optional request parameter, which uses a "Y"/"N" indicator to determine whether to retrieve filing errors and/or warnings.

Users can specify the option to retrieve Upload errors and/or warnings that may have occurred during rules or footnotes upload and fares batch data errors and/or warnings during fares upload through the parameter retrieveUploadErrors, which is a "Y"/"N" indicator. They can also opt to display errors associated to upload attempts on or after the selected timestamp by using the parameter afterTimestamp. API request with no timestamp display all errors related to all upload attempts. The API response will list up to 400 error messages for each product (Fares, Rules, and Footnotes). If there are more than 400 errors per product, please manually log in to the 3270 Upload Transmission Job Status Display to view all errors.

Data providers may also opt in the request to retrieve justifications associated with the specified work units through the parameter retrieveJustifications, which is a "Y"/"N" indicator

Request Header Parameters

See OAuth Access Tokens and Authentication for full instructions on header parameters needed for authentication.

Request URL Parameters

Requests can be made by specifying at least one of the following URL parameters:

Parameter(s) Description Type Format Example
createDate Date the work unit was created [workUnitName must also be specified if createDate is used] String Seven characters of the format DDMMMYY where DD is two numeric characters signifying the day of the month, MMM is three alphabetic characters signifying the first three letters of the month name, and YY is two numeric characters signifying the year "17MAR18"
retrieveFilingErrors (optional) Determines whether to retrieve filing errors and/or warnings that may have occurred during the release (default is "Y") String "Y": retrieve filing validation errors and/or warnings; "N": do not retrieve filing validation errors and/or warnings "Y"
retrieveUploadErrors (optional) Determines whether to retrieve upload errors for the specified work unit (default is "N"). The API response will list up to 400 error messages for each product (Fares,Rules and Footnotes). If there are more than 400 errors per product, please manually log in to the 3270 Upload Transmission Job Status Display to view all errors. String "Y": retrieve upload errors and/or warnings; "N": do not retrieve upload errors and/or warnings "Y"
afterTimestamp (optional) The date and time used to display errors associated to upload attempts submitted on or after the selected time. API requests with no timestamp display all errors related to all upload attempts. String Expected Format is yyyy-MM-dd'T'HH:mm:ss.SSS where yyyy is four numeric characters signifying the year,MM is two numeric characters signifying the month, dd is two numeric characters signifying the day of the month,HH is two numeric characters signifying the hour,mm is two numeric characters signifying the minute,ss is two numeric characters signifying the second and SSS is three numeric characters signifying the millisecond "2019-07-24T00:01:00.000"
retrieveJustifications (optional) Determines whether to retrieve justifications for the specified work unit (default is "N") String "Y": retrieve justifications; "N": do not retrieve justifications "Y"
workUnitId Unique identifier assigned to a work unit String Alphanumeric between 10-17 characters, including (in order) 1) the 2-3 character org code (XXX), 2) the create date, and 3) the work unit number: XXX-DDMMMYY-NNNNNNN "XXX-17MAR18-1234567"
workUnitName Unique name assigned to a work unit String Alphanumeric between 0-10 characters that permits the special characters hyphen (-), forward slash (/), comma (,), period (.) "09-A1456"
partnerOrgCode Unique identifier assigned to an organization String Alphanumeric between 2-3 characters "91"

Response

Upon successful processing of a request, a response is provided with the following details about the matched work unit(s) and batch(es):

Response Parameters

Work Unit Details

Parameter Description Type Example
createDate Date the work unit was created String "17MAR18"
contents Collection of dictionaries describing batches in the returned work unit(s) String [ { "batchID": "9102259", ... } ]
description Free-form text that describes the content or initiative of the work unit String "free-form text"
distributedTime Date and time the work unit was distributed String ""2017-11-17 12:01:02.540696"
exclusiveAccess Flag indicating whether or not access to the work unit is restricted to the organization that created it String "Y"
totalWorkUnits Number of work units returned Number 1
workUnitId Unique identifier assigned to work unit String "XXX-17MAR18-1234567"
workUnitName Unique name assigned to a work unit String "09-A1456"
workUnits Collection with the contents of all returned work units String [ { "contents": [ ... ], ... } ]
workUnitStatus The status of the work unit at the time the request was processed String "Distributed"

Batch Details

Parameter Description Type Example
batchID A code identifying a batch (group) of transactions String "9102259"
batchType Identifies whether the content of the batch is Fares, Rules or Footnotes String "Footnotes"
carrier As defined by ATPCO; generally an airline String "XXX"
fanNumber Filing advice number (FAN) String "17NOV17-AAY"
global Entity that defines geographic scope String "US"
recordCount Number of transactions associated to the batch String "1"
tariff Entity that is defined by system, geographic scope, and distribution process String "PF17"
validationLevel Level of filing validation applied to fare, rule, and footnote data String "Limited"

Rules Upload Errors and Warnings

Parameter Description Type Example
carrierCode As defined by ATPCO; generally an airline String "XXX"
lineNum Line number in the rules upload file where the error/warning occured String "4"
message Describes the rules upload error or warning String "Invalid number of records in the work unit of 00005"
rule Rule code associated with the tariff String "1680"
tariffCode Entity that is defined by system, geographic scope, and distribution process String "IPRA"
timestamp Timestamp of the rules upload String "2019-12-18 14:51:07.104"

Footnotes upload Errors and Warnings

Parameter Description Type Example
carrierCode As defined by ATPCO; generally an airline String "XXX"
lineNum Line number in the footnotes upload file where the error/warning occured String "4"
message Describes the footnotes upload error or warning String "Invalid number of records in the work unit of 00005"
tariffCode Entity that is defined by system, geographic scope, and distribution process String "TAFP"
timestamp Timestamp of the footnotes upload String "2019-12-18 14:51:07.104"

Fares Upload Errors and Warnings

Parameter Description Type Example
carrierCode As defined by ATPCO; generally an airline String "XXX"
fareKey Batch and Transaction details
FareKey format for Transaction errors:
INTERNATIONAL - “F-BatchPrefixCd BatchNumber-LOC1-LOC2-FC-OW-FTN-RTG-CURR-EFFDT"
DOMESTIC – “V-BatchPrefixCd BatchNumber-LOC1-LOC2-FC-OW-FTN-RTG-CURR-EFFDT"
ADDON - “A-BatchPrefixCd BatchNumber-LOC1-LOC2-FC-OW-FTN-RTG-CURR-EFFDT-ZONE"
FareKey format for Batch level errors:
“B-BatchPrefixCd BatchNumber”		 String "F-81 10089-NYC-PAR-CBS3-N--0-USD-2019-12-12"
message Describes the fares batch data error or warning during fares upload String "Invalid number of records in the work unit of 00005"
tariffCode Entity that is defined by system, geographic scope, and distribution process String "TAFP"
timestamp Timestamp of the fares upload String "2019-12-18 14:51:07.104"

Justifications

Parameter Description Type Example
carrier As defined by ATPCO; generally an airline String "XXX"
tariff Entity that is defined by system, geographic scope, and distribution process String "TAFP"
government Government to which the justification applies String "XXX"
effectiveDate Justification effective date of the data in the work unit String "28MAR19"
justificationText Free-form justification text within the work unit for the specified government/carrier/tariff String "ADDING FARES TO REMAIN COMPETITIVE"

Example Requests and Responses

The following examples show what the Retrieve Work Unit Summary Content Web Service would return based on the indicated requests.

Request with Work Unit ID and Retrieve Filing Error Parameter Specified

request response
Copy
Copied
GET https://developer.atpco.net/services/gtst/v1/distribution/wusummary/workunit?createDate=&workUnitName=&workUnitId=91-16AUG18-47&retrieveFilingErrors=Y
Copy
Copied
{
   "totalWorkUnits" : 1,
   "workUnitId" : "91-16AUG18-47",
   "workUnits" : [
      {
         "workUnitId" : "91-16AUG18-47",
         "workUnitName" : "",
         "workUnitStatus" : "Incomplete w/Errors",
         "exclusiveAccess" : "Y",
         "distributedTime" : "9999-12-31 00:00:00.0",
         "description" : "",
         "contents" : [
            {
               "batchID" : "9100991",
               "batchType" : "Footnotes",
               "carrier" : "91",
               "global" : "EH",
               "recordCount" : 1,
               "tariff" : "EUAFZ",
               "validationLevel" : "Partial"
            },
            {
               "batchID" : "9102476",
               "batchType" : "Rules",
               "carrier" : "91",
               "global" : "EH",
               "recordCount" : 4,
               "tariff" : "IPREUAZ",
               "validationLevel" : "Partial"
            },
            {
               "batchID" : "9110939",
               "batchType" : "Fares",
               "carrier" : "91",
               "global" : "EH",
               "recordCount" : 2,
               "tariff" : "EUAFZ",
               "validationLevel" : "Partial"
            },
            {
               "batchID" : "9110940",
               "batchType" : "Fares",
               "carrier" : "91",
               "global" : "EH",
               "recordCount" : 2,
               "tariff" : "AARBAEZ",
               "validationLevel" : "Partial"
            }
         ],
         "msgs" : [
            {
               "level" : "WU RELEASE ERROR",
               "details" : [
                  {
                     "message" : "Effective date of the Fare Class must be equal to or one day greater than work unit release date as allowed by the Rules tariff",
                     "subDetails" : [
                        "Carrier:91,Tariff:IPREUAZ,Rule:8171,Fare Class:LA8171,Sequence:5000000,Display Type:E,Eff Date:16AUG18,Disc Date:,Batch Id:91 2476"
                     ]
                  },
                  {
                     "message" : "Effective date of the rule category must be equal to or one day greater than work unit release date as allowed by the Rules tariff",
                     "subDetails" : [
                        "Carrier:91,Tariff:IPREUAZ,Rule/Footnote:8171,Category:01,Sequence:5000000,Eff Date:16AUG18,Disc Date:,Batch Id:91 2476"
                     ]
                  },
                  {
                     "message" : "Effective date of the RBD must be equal to or one day greater than work unit release date as allowed by the Rules tariff",
                     "subDetails" : [
                        "Carrier:91,Tariff:IPREUAZ,Rule:0000,Eff Date:16AUG18,Disc Date:,Batch Id:91 2476",
                        "Carrier:91,Tariff:IPREUAZ,Rule:8171,Eff Date:16AUG18,Disc Date:,Batch Id:91 2476"
                     ]
                  },
                  {
                     "message" : "Effective date of the Footnote must be equal to or one day greater than work unit release date as allowed by the Footnote tariff",
                     "subDetails" : [
                        "Carrier:91,Tariff:EUAFZ,Rule/Footnote:1B,Category:23,Sequence:100000,Eff Date:16AUG18,Disc Date:,Batch Id:91 991"
                     ]
                  }
               ]
            },
            {
               "level" : "WU RELEASE WARNINGS",
               "details" : [
                  {
                     "message" : "No matching Fare Class(es) found for Addon",
                     "subDetails" : [
                        "Carrier:91,Tariff:AARBAEZ,Zone:100,Nation:BE,Orig:BRU,Nation:ES,Dest:LEU,Fare Class:A*****,OW/RT:1,Routing:0000,Footnote:,Eff Date:17AUG18,Disc Date:,Batch Id:91 10940"
                     ]
                  }
               ]
            }
         ]
      }
   ]
}

Request with Work Unit ID and Retrieve Justification Parameter Specified

request response
Copy
Copied
GET https://developer.atpco.net/services/gtst/v1/distribution/wusummary/workunit?workUnitId=ATP-14MAR19-14&retrieveFilingErrors=N&retrieveJustifications=Y
Copy
Copied
{
    "retrieveFilingErrors": "N",
    "retrieveJustifications": "Y",
    "totalWorkUnits": 1,
    "workUnitId": "ATP-14MAR19-14",
    "workUnits": [
        {
            "workUnitId": "ATP-14MAR19-14",
            "workUnitName": "3",
            "workUnitStatus": "Distributed",
            "exclusiveAccess": "Y",
            "distributedTime": "2019-03-15 00:03:08.315495",
            "description": "",
            "contents": [
                {
                    "batchID": "8118612",
                    "batchType": "Fares",
                    "carrier": "91",
                    "fanNumber": "14MAR19-AAG",
                    "global": "AT",
                    "recordCount": 1,
                    "tariff": "AUSA",
                    "validationLevel": "Full"
                }
            ],
            "justifications": [
                {
                    "carrier": "91",
                    "effectiveDate": "",
                    "govemment": "DE",
                    "justificationText": "ADDING FARES TO REMAIN COMPETITIVE",
                    "tariff": "AUSA"
                }
            ]
        }
    ]
}

Request with Work Unit ID and Retrieve Upload Errors Parameter Specified

request response
Copy
Copied
GET https://developer.atpco.net/services/gtst/v1/distribution/wusummary/workunit?workUnitId=ATP-18dec19-8&retrieveUploadErrors=Y&afterTimestamp=2019-07-24T00:01:00.000
Copy
Copied
{
  "afterTimestamp": "2019-07-24T00:01:00.000",
  "retrieveFilingErrors": "Y",
  "retrieveJustifications": "N",
  "retrieveUploadErrors": "Y",
  "totalWorkUnits": 1,
  "workUnitId": "ATP-18DEC19-8",
  "workUnits": [
    {
      "workUnitId": "ATP-18DEC19-8",
      "workUnitName": "106673",
      "workUnitStatus": "Incomplete",
      "exclusiveAccess": "Y",
      "distributedTime": "9999-12-31 00:00:00.0",
      "description": "RULES UPLOAD",
      "contents": [
        {
          "batchID": "8111001",
          "batchType": "Rules",
          "carrier": "91",
          "global": "AT",
          "recordCount": 3,
          "tariff": "IPRA",
          "validationLevel": "Full"
        },
        {
          "batchID": "8110089",
          "batchType": "Fares",
          "carrier": "91",
          "global": "AT",
          "recordCount": 0,
          "tariff": "TAFP",
          "validationLevel": "Partial"
        },
        {
          "batchID": "8110088",
          "batchType": "Footnotes",
          "carrier": "91",
          "global": "AT",
          "recordCount": 0,
          "tariff": "TAFP",
          "validationLevel": "Partial"
        }
      ],
      "uploadErrorsWarnings": {
        "footnotes": {
          "errors": [
            {
              "carrierCode": "91",
              "tarriffCode": "TAFP",
              "footnote": "V",
              "lineNum": "4",
              "message": "Effective date must be greater than today for non-EDOT tarrif TAFP at row 000000004",
              "timestamp": "2019-08-01 23:30:59.371"
            }
          ],
          "warnings": [
            {
              "carrierCode": "91",
              "tarriffCode": "TAFP",
              "footnote": "",
              "lineNum": "1",
              "message": "Invalid Number of Records In The Work Unit Of 00005",
              "timestamp": "2019-08-01 23:30:57.141"
            }
          ]
        },
        "rules": {
          "msg": "There are more than 400 errors/warnings. Please log into Upload Transmission Job Status Display to view the additional errors/warnings.",
          "errors": [
            {
              "carrierCode": "91",
              "lineNum": "4",
              "message": "INVALID PASSENGER TYPE CODE OF XXX",
              "rule": "1000",
              "tarriffCode": "IPRA",
              "timestamp": "2019-12-18 14:51:07.104"
            }
          ]
        },
        "fares": {
          "errors": [
            {
              "carrierCode": "91",
              "tarriffCode": "TAFP",
              "fareKey": "F-81 10089-NYC-PAR-CBS3-N--0-USD-2019-12-12",
              "message": "Effective date must be greater than today for non-EDOT tarrif TAFP at row 000000004",
              "timestamp": "2019-08-01 23:30:59.371"
            }
          ],
          "warnings": [
            {
              "carrierCode": "91",
              "tarriffCode": "TAFP",
              "fareKey": "F-81 10089-NYC-PAR-CBS3-N--0-USD-2019-12-12",
              "message": "Invalid Number of Records In The Work Unit Of 00005",
              "timestamp": "2019-08-01 23:30:57.141"
            }
          ]
        }
      }
    }
  ]
}

Request to Retrieve Partner Work Units

(with workUnitName, createDate, and partnerOrgCode parameter specified in the request)

request response
Copy
Copied
GET https://developer.atpco.net/services/gtst/v1/distribution/wusummary/workunit?workUnitName=test&partnerOrgCode=91&createDate=12MAR21
Copy
Copied
{
  "totalWorkUnits": 2,
  "workUnitName": "TEST",
  "createDate": "12MAR21",
  "partnerOrgCode": "91",
  "retrieveFilingErrors": "Y",
  "retrieveJustifications": "N",
  "workUnits": [
    {
      "workUnitId": "91-12MAR21-2",
      "workUnitName": "TEST",
      "workUnitStatus": "Incomplete w/Errors",
      "exclusiveAccess": "N",
      "distributedTime": "9999-12-31 00:00:00.0",
      "description": "",
      "contents": [
        {
          "carrier": "91",
          "global": "AT",
          "tariff": "IPRA",
          "batchType": "Rules",
          "batchID": "9100673",
          "validationLevel": "Full",
          "recordCount": 0
        },
        {
          "carrier": "91",
          "global": "AT",
          "tariff": "IPRA",
          "batchType": "Rules",
          "batchID": "9113358",
          "validationLevel": "Limited",
          "recordCount": 0
        }
      ],
      "msgs": [
        {
          "level": "WU RELEASE ERROR",
          "details": [
            {
              "message": "Following Batch(es) did not complete successfully",
              "subDetails": [
                "Carrier:91,Tariff:IPRA,Batch Id:91 13358,Batch Type:Rules",
                "Carrier:91,Tariff:IPRA,Batch Id:91 673,Batch Type:Rules"
              ]
            }
          ]
        }
      ]
    },
    {
      "workUnitId": "91-12MAR21-1",
      "workUnitName": "TEST",
      "workUnitStatus": "Incomplete",
      "exclusiveAccess": "N",
      "distributedTime": "9999-12-31 00:00:00.0",
      "description": "",
      "contents": [
        {
          "carrier": "91",
          "global": "AT",
          "tariff": "IPRA",
          "batchType": "Rules",
          "batchID": "9113303",
          "validationLevel": "Limited",
          "recordCount": 0
        }
      ]
    }
  ]
}

Request to Retrieve Partner Work Units

(with workUnitId parameter specified in the request)

request response
Copy
Copied
GET https://developer.atpco.net/services/gtst/v1/distribution/wusummary/workunit?workUnitId=91-03APR21-1
Copy
Copied
{
    "totalWorkUnits":1,
    "workUnitId":"91-03APR21-1",
    "retrieveFilingErrors":"Y",
    "retrieveJustifications":"N",
    "retrieveUploadErrors":"N",
    "afterTimestamp":"",
    "workUnits":[
        {
            "workUnitId":"91-03APR21-1",
            "workUnitName":"REAS",
            "workUnitStatus":"Incomplete",
            "exclusiveAccess":"N",
            "distributedTime":"9999-12-31 00:00:00.0",
            "description":"FARES",
            "contents":[
                {
                    "carrier":"91",
                    "global":"CA",
                    "tariff":"CF1",
                    "batchType":"Fares",
                    "batchID":"9115458",
                    "validationLevel":"Full",
                    "recordCount":0
                }
            ]
        }
    ]
}