Modify Work Unit Web Service

Use the Modify Work Unit Web Service to add justification for a Carrier/Tariff/Government to eligible work units. With the Modify Work Unit Web Service, you can also modify and add data to existing work units that are used in workflows for distribution of fares, rules and footnotes data.

Request

Your request to the Modify Work Unit 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 parameters to add justification and/or reassign batches in the request along with the Work Unit ID in the request body:

  • Work Unit ID - Work Unit ID where justification is added, and the batches are being moved

Parameters to add justification:

  • Carrier - Carrier to which the justification applies
  • Tariff - Tariff to which the justification applies
  • Government - Government to which the justification applies
  • Justification Text - Free-form text that will populate the justification within the work unit for the specified Carrier/Tariff/Government

Additionally, you may opt to specify:

  • Justification Effective Date - Effective Date to be used to validate against the effective date of the data in the work unit

Parameters to reassign batches:

  • Source Work Unit ID - Work unit ID where the batch is being moved from
  • Rules Batch IDs - Rules batch ID that is being moved from one work unit to another
  • Fares Batch IDs - Fares batch ID that is being moved from one work unit to another
  • Footnotes Batch IDs - Footnotes batch ID that is being moved from one work unit to another

A maximum of 20 batch IDs can be specified per request. When the source Work Unit ID is specified, at least one batch to reassign is required. Upon successful processing of request, batches will be reassigned and the justification for the Carrier/Tariff/Government will be associated to the specified work unit. Justification will be added to the work unit only if the reassign is successful.

You may also update existing justification within a work unit.

Request Header Parameters

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

Request Body

The request body should be formatted as a JSON object, which must include the required parameters and can additionally include the optional parameter.

Request Object Parameters

The request object must include the following parameters:

Parameter Description Type Format Example
workUnitID Unique identifier assigned to 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"
carrier As defined by ATPCO; generally, an airline string Alphanumeric, 2 characters "XX"
tariff Entity that is defined by system, geographic scope, and distribution process string Alphanumeric between 1-7 characters "O3A415"
government Government to which the justification applies string Alphabetic, 2 characters "US"
justificationText Free-form text that will populate the justification within the work unit for the specified government/carrier/tariff string Alphanumeric between 0-632 characters that permits blank spaces and the special characters hyphen (-), forward slash (/), percent sign (%), asterisk (*), pound/hash (#), and period (.). "***This is example justification text."
effectiveDate (Optional) Effective date that will populate the justification within the work unit for the specified government/carrier/tariff 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"
sourceWorkUnitID Unique identifier assigned to 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"
rulesBatchIds Unique identifier assigned to rules batch string 7 characters, including (in order) 1) the 2 character batch ID (XX), 2) the batch number (NNNNN) "91 1234"
fareBatchIds Unique identifier assigned to fares batch string 7 characters, including (in order) 1) the 2 character batch ID (XX), 2) the batch number (NNNNN) "91 1234"
footnotesBatchIds Unique identifier assigned to footnotes batch string 7 characters, including (in order) 1) the 2 character batch ID (XX), 2) the batch number (NNNNN) "91 1234"

Response

Upon successful processing of a request, summary of added justifications and reassigned batches for the work unit is returned.

The response to a successful Modify Work Unit service call will contain a JSON object including the parameters specified in the request body and messages detailing the results of the request.

Example response object

Copy
Copied
{
  "workUnitId": "91-28MAR19-1",
  "msg": "Submit request was successful",
  "reassign": {
     "sourceWorkUnitId": "91-28MAR19-2",
     "batches": {
        "faresBatchIds": "91 33054",
        "rulesBatchIds": "91 33055","91 33056"
      },
     "msgList": [
            {
         "level": "INFO",
         "details": [
               "Batch(es) successfully reassigned"
          ],
        }
      ],
  },
  "justifications": [
    {
      "government": "GB",
      "effectiveDate": "28MAR19",
      "justificationText": "API JUSTIFICATION",
      "carrier": "91",
      "tariff": "IPRA",
      "msgList": [
        {
          "level": "INFO",
          "details": [
            "Justification saved successfully"
          ],
        }
      ],
    }
  ],
}

Response Parameters

The response object can include the following parameters:

Parameter Description Type Example
workUnitId Work unit ID where justification is added and the batches are being moved to string "XXX-17MAR18-1234567"
details Describes message; prefixed by the associated parameter collection of strings [ "Justification saved successfully" ]
carrier Carrier to which the justification applies string "XX"
tariff Tariff to which the justification applies string "O3A415"
government Government to which the justification applies string "US"
justificationText Free-form text that will populate the justification within the work unit for the specified government/carrier/tariff string "***This is example justification text."
effectiveDate Effective Date to be used to validate against the effective date of the data in the work unit string "110419"
justifications Grouping of justification details to be added to specified Work Unit collection of maps [ { ..., ..., ... } }
level Describes message level as ERROR or INFO string "INFO"
msg Top-level message (used for errors and system messages) string "Submit request was successful"
msgList Grouping of work unit release messages per Work Unit string [ { "level": "INFO", "details": [ "Justification saved successfully" ] }, {...} ]
sourceWorkUnitID Work unit ID where the batch is being moved from string "XXX-17MAR18-1234567"
rulesBatchIds Rules batch ID that is being moved from one work unit to another string "91 1234"
fareBatchIds Fares batch ID that is being moved from one work unit to another string "91 1234"
footnotesBatchIds Footnotes batch ID that is being moved from one work unit to another string "91 1234"
reassign Grouping of batch details to be reassigned to specified Work Unit collection of maps { { ..., ..., ... } }

Example Requests and Responses

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

Request to Add Single Justification to a Work Unit

request response
Copy
Copied
{
  "workUnitId": "ATP-28MAR19-1",
  "justifications": [
    {
      "carrier": "91",
      "tariff": "IPRA",
      "effectiveDate": "28MAR19",
      "justificationText": "API JUSTIFICATION",
      "government": "GB"	
    }
  ]
}
Copy
Copied
{
  "workUnitId": "ATP-28MAR19-1",
  "msg": "Submit request was successful",
  "justifications": [
    {
      "government": "GB",
      "effectiveDate": "28MAR19",
      "justificationText": "API JUSTIFICATION",
      "carrier": "91",
      "tariff": "IPRA",
      "msgList": [
        {
          "level": "INFO",
          "details": [
            "Justification saved successfully"
          ],
        }
      ],
    }
  ],
}

Request to Add Multiple Justifications to a Work Unit

request response
Copy
Copied
{
  "workUnitId": "ATP-28MAR19-1",
  "justifications": [
    {
      "carrier": "91",
      "tariff": "IPRA",
      "effectiveDate": "28MAR19",
      "justificationText": "API JUSTIFICATION1",
      "government": "GB"	
    },
    {
      "carrier": "91",
      "tariff": "TAFP",
      "effectiveDate": "28MAR19",
      "justificationText": "API JUSTIFICATION2",
      "government": "GB"	
    }
  ]
}
Copy
Copied
{
  "workUnitId": "ATP-28MAR19-1",
  "msg": "Submit request was successful",
  "justifications": [
    {
      "government": "GB",
      "effectiveDate": "28MAR19",
      "justificationText": "API JUSTIFICATION1",
      "carrier": "91",
      "tariff": "IPRA",
      "msgList": [
        {
          "level": "INFO",
          "details": [
            "Justification saved successfully"
          ],
        }
      ],
    },
    {
      "government": "GB",
      "effectiveDate": "28MAR19",
      "justificationText": "API JUSTIFICATION2",
      "carrier": "91",
      "tariff": "TAFP",
      "msgList": [
        {
          "level": "INFO",
          "details": [
            "Justification saved successfully"
          ],
        }
      ],
    }
  ],
}

Request to Update Existing Justification

request response
Copy
Copied
{
  "workUnitId": "ATP-28MAR19-1",
  "justifications": [
    {
      "carrier": "91",
      "tariff": "IPRA",
      "effectiveDate": "28MAR19",
      "justificationText": "API JUSTIFICATION 123 UPDATE",
      "government": "US"	
    }
  ]
}
Copy
Copied
{
  "workUnitId": "ATP-28MAR19-1",
  "msg": "Submit request failed",
  "justifications": [
    {
      "government": "US",
      "effectiveDate": "28MAR19",
      "justificationText": "API JUSTIFICATION 123 UPDATE",
      "carrier": "91",
      "tariff": "IPRA",
      "msgList": [
        {
          "level": "INFO",
          "details": [
            "Justification saved successfully"
          ],
        }
      ],
    },
  ],
}

Request to Reassign Batches to a Work Unit without Justification

request response
Copy
Copied
{
  "workUnitId": "91-28MAR19-1",
  "reassign":
 { 
   "sourceWorkUnitId":"91-28MAR19-2",
    "batches":{
    "faresBatchIds":"91 33054"
    }
  }    
}
Copy
Copied
{
  "workUnitId": "91-28MAR19-1",
  "msg": "Submit request was successful",
  "reassign": {
     "sourceWorkUnitId": "91-28MAR19-2",
     "batches": {
        "faresBatchIds": "91 33054"
        },
     "msgList": [
            {
         "level": "INFO",
         "details": [
               "Batch(es) successfully reassigned"
          ],
        }
      ],
  }
}

Request to Reassign Batches to a Work Unit with Justification

request response
Copy
Copied
{
  "workUnitId": "91-28MAR19-1",
  "reassign":
 { 
   "sourceWorkUnitId":"91-28MAR19-2",
    "batches":{
    "faresBatchIds":"91 33054",
    "rulesBatchIds":"91 33055",
    "footnotesBatchIds":"91 33056"
    }
  },
  "justifications": [
    {
      "carrier": "91",
      "tariff": "IPRA",
      "effectiveDate": "28MAR19",
      "justificationText": "API JUSTIFICATION",
      "government": "GB"	
    }
  ]    
}
Copy
Copied
{
  "workUnitId": "91-28MAR19-1",
  "msg": "Submit request was successful",
  "reassign": {
     "sourceWorkUnitId": "91-28MAR19-2",
     "batches": {
        "faresBatchIds": "91 33054",
        "rulesBatchIds":"91 33055",
        "footnotesBatchIds":"91 33056"
     },
     "msgList": [
            {
         "level": "INFO",
         "details": [
               "Batch(es) successfully reassigned"
          ],
        }
      ],
  },
   "justifications": [
    {
      "government": "GB",
      "effectiveDate": "28MAR19",
      "justificationText": "API JUSTIFICATION",
      "carrier": "91",
      "tariff": "IPRA",
      "msgList": [
        {
          "level": "INFO",
          "details": [
            "Justification saved successfully"
          ],
        }
      ],
    }
  ],
}