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 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 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 occurred | 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 occurred | 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 with Work Unit ID and Retrieve Justification Parameter Specified
Request
Response
Request with Work Unit ID and Retrieve Upload Errors Parameter Specified
Request
Response
Request to Retrieve Partner Work Units
(with workUnitName, createDate, and partnerOrgCode parameter specified in the request)
Request
Response
Request to Retrieve Partner Work Units
(with workUnitId parameter specified in the request)
Request
Response