Update the Non-Predefined Line Item DE Values of Terminal Records

PUT /ws/rest/service/v2/bp/record/cleanup/terminallines

Available: 26.4 and later

Purpose

To update the line item values for customer-created data elements (DEs) of business process (BP) records that have reached a Status of Terminal. The integration interface created for the BP in uDesigner determines which DEs are available for update.

To update a specific line item, you must include the internal Line Number (li_num) value. Note that li_num cannot be added as a DE on a detail form. However, it is visible as the default first column in the line item logs.

This service supports DEs for data definition (DD) types:
  • Checkbox
  • Date/Time
  • Integer
  • Integer PD
  • Radio Button
  • String
  • String PD
This service does not support:
  • DEs that start with uuu
  • System-based DEs
  • DEs that include a value for Pre-Defined Category in Data Structure Setup
  • DEs for DD types:
    • Currency
    • Decimal
    • Rich Text
  • Radio Button
  • String
  • String PD

Additional Information

You can update the following:
  • BP records at the company or project/shell level
  • Workflow and Non-Workflow BP records

No additional record processing occurs after the update. Any configured formulas, advanced formulas, QBDE trigger elements, autocreation, and so on are not updated. If line item data is included in a payload, it is ignored.

Updates are logged in both the BP Record Audit Log and the REST Service Audit Log.

Prerequisites

Ensure that the integration user has the Update permissions for Business Process Services to process the requests. For more information, see Creating Integration Users.

Request Format

Send a request as a JSON Map with the following structure:

{

"options":

{"bpname":"<value>",

"project_number": "<value>"},

"data":[ {"record_no":["<value>","<value>"]}]

}

Request Parameters

Specify the following parameter in the Options JSON map:

Request Parameter Line Item Data Required? Data Type Description
bpname   Yes String

Name of the BP that has reached Terminal status
project_number   Yes String A valid shell number
record_no   Yes String BP record number
  _bp_lineitems Yes Integer Collection of line items included in the request
  li_num Yes Integer System-generated line number
  uuu_tab_id Yes Integer Name of the tab
  <DE to update> Yes   DE that you want to update, such as a custom DE

Response Format

A JSON object is returned in the following format.

{

"data": [ ],

"message": "<list of messages>",

"status": <REST status code value>,

"rest_audit_id": <ID from rest audit table>

}

A successful response displays a status code 200.

A failed response displays a message with a status code:
  • Status – 3000: None of the records were successfully updated
  • Status – 12773: Partial records were successfully updated

If there is a partial failure, the response provides details about each record, indicating which ones were successful and which ones had validation errors.

Sample Success Request to Update Line Items

To update Contracts record for project PRJ-004, send a request in the following format:

{

"options": {

"project_number": "2020 - 5",

"bpname": "Generic Line Item"

},

"data": [

{

"record_no":"uxgli-0149",

"_bp_lineitems": [

{

"Postal_Code_2": 93435,

"stringpull2": "Label2",

"A1":"rest update3",

"li_num": "1"

}

]

}

]

}

Sample Success Response to Update Line Items

A successful response with status code 200 displays in the following format:

{

"data": [],

"message": [

"[uxgli-0149] Updated successfully."

],

"status": 200,

"rest_audit_id": 45

}

Sample Failed Response 1

{

"data": [],

"message": ["Business Process Name is not correct."],

"status": 17002,

"rest_audit_id": 721

}

Sample Request to Update Line Items for BP Record that is Not Terminated

To update Generic Line Item record for project 2020 - 5, send a request in the following format:

{

"options": {

"project_number": "2020 - 5",

"bpname": "Generic Line Item"

},

"data": [

{

"record_no":"uxgli-0147",

"_bp_lineitems": [

]

},

{

"record_no":"uxgli-0148",

"_bp_lineitems": [

{

"Postal_Code_2": 93435,

"stringpull2": "Label2",

"A1":"rest update3",

"li_num": "1"

}

]

},

{

"record_no":"uxgli-0149",

"_bp_lineitems": [

{

"Postal_Code_2": 93435,

"stringpull2": "Invalid Label",

"A1":"rest update3",

"li_num": "1"

}

]

}

]

}

Sample Failed Response for Updating Line Items

A failed response to the above request displays validation errors with the corresponding status code in the following format:

{

"data": [],

"message": [

"[uxgli-0147] No Line items found in payload",

"[uxgli-0148] Record is not in terminated status",

"[uxgli-0149] Updated successfully."

],

"status": 12773,

"rest_audit_id": 46

}

Sample Request to Update Line Items with Linked Elements

To update Generic Line Item record for project 2020 - 5 when it contains linked elements, send a request in the following format:

{

"options": {

"project_number": "2020 - 5",

"bpname": "Generic Line Item"

},

"data": [

{

"record_no":"uxgli-0145",

"_bp_lineitems": [

li_num: 1,

ugenProjectName:"this is a linked element"

]

}

]

}

Sample Failed Response for Updating Line Items with Linked Elements

A failed response displays for the above request in the following format:

{

"data": [],

"message": [

"[uxgli-0145] Linked Elements cannot be updated."

],

"status": 12797,

"rest_audit_id": 50

}

Supported Validation Messages and Status Codes

The following error messages and status codes display in the response when incorrect values are provided in the request:

Field Name Use-case Scenario Status Code Error Message
bpname BP name is not specified 603 Business Process Name is required
bpname BP name does not exist 603 Business Process Name is not correct
bpname Specified BP is Inactive 3006 Business Process is not Active
record_no Record number is not specified 17004 Record number is required
record_no Specified record number does not exist 12756 [Record Numbers] do not exist
record_no Specified record is not in Terminated status 12780 Record is not in terminal status
record_no Only a partial list of records is successfully updated 12773 [List of record numbers] updated successfully

Error records include a message that indicates why the record update failed.
record_no When there are duplicate records 12779 Duplicate records found
project_number When project number is not provided 13001 Specified project number does not exist
project_number Project status is inactive 602 Project status is Inactive
project_number Multiple project numbers specified in input parameter   1245 Project/Shell Number is not correct
<field targeted for update> When the request contains an unsupported data type   12774 The request contains one or more data elements of an unsupported data type
<DE to update> When the request contains a predefined or system DE   12775 The request contains one or more predefined system data elements which cannot be updated
<DE to update> When no valid DEs are found for the update   12777 No eligible data elements found to update

Supported Error Messages and Status Codes for Line Item Data

The following error messages and status codes display in the response when incorrect values are provided in the request:

Number Error Condition Error Code Error Message
1. Linked elements are being updated 12797 Linked Elements cannot be updated.
2. Duplicate li_num and uuu_tab_id combination in payload 12794 Duplicate line item(s) in the request: Each (li_num, uuu_tab_id) pair must be unique per lineitem update.
3. When no entry is found for li_num and uuu_tab_id combination 12793 No line items matched to update for one or more tab(s): no Line Item exists for specified (li_num, uuu_tab_id) pair in this record/tab context.
4. When uuu_tab_id value is missing or incorrect 12792 Missing or invalid uuu_tab_id for line item update.
5. When li_num value is missing or incorrect 12791 Missing or blank li_num for line item update
6. For a string type DE, when an input data length exceeds maximum allowed 12796 Value exceeds maximum allowed size: <size>
7. When input does not contain any line item data for update 12789 No line items found in payload.