Update BP Record with Attachment

Purpose

Update a record with attachments for the following types of BPs:

Shell-level BPs based on a project_number
Company-level BPs if the project/shell number is not provided

This REST service uses the Step form to update the BP record. All required fields and validation rules run against the Step form used in the workflow details. The form in the End step is a View Form, and cannot be updated.

Note:

Only one record update with attachment is supported in this call.
Republish is supported only when you route the record to the next step manually in the Unifier web application. Republish is not supported when you route the BP record to the next step by using REST services.

Prerequisite

To add attachments to line item records, ensure that you have selected the Allow Attachments to Line Items checkbox only for the Custom Detail Form in uDesigner.

Request Format

All parameters must be URL encoded. The request body and response body use JSON format.

Note:

If the file exists in a record, the service ignores it and does not revise it.
If the Step form has "add attachment" disabled, files are not attached.
If the "_attachment" field outside the data list for a ZIP file is not provided, the record is updated without attachment.
Field properties such as Read-only in the Step form are retained.
Mandatory fields in the Step form must be present in the Integration form with Direction set as Both or Input.
Field direction provided in the Integration form is retained.
Auto-Creation settings are mandatory in the Shell or Company BP Setup in Admin mode. During autocreation, if the value in a BP picker does not meet the filtering conditions that have been configured for the created BP, the system does not copy the picker value and leaves it blank. In addition, on the Step form of the created BP, any data elements (DEs) that are configured to auto-populate from the picker are cleared.
In input JSON options, project_number specifies the shell in which the records exist. If project_number is not provided, the records are from the company level.
record_no is mandatory and is a part of the data.
bpname is mandatory and is part of the options form parameter.
If a Workflow BP record has already been accepted by an assignee, the Update REST call fails with the message: Record has already been accepted by Task Assignee.
WFCurrentStepName and WFActionName are part of workflow_details and apply to Workflow type BPs. If you provide WFCurrentStepName and WFActionName, the record is updated and sent to next workflow step. If you do not provide these values, the record is updated and remains on the same workflow step.
LineItemIdentifier is part of the options form parameter. The LineItemIdentifier value is the DE name present in the line item. That DE must be present in data in the input record JSON with its value.
The optimizedPickerExecution option is part of the options form parameter. This option controls picker populate behavior for existing line items. Valid values are true and false.
When the value is true, the input JSON for the Upper Form or Lineitem Form must include the Data Picker DE tag and its value. This action triggers populate behavior for other data elements that are configured by design. If the input JSON does not include the Data Picker DE property, the system does not process the Data Picker DE as part of the update and does not populate values from the data picker record in the current record and updated line items.

When the value is false, or if the option is not present, the system continues to use the existing behavior.
If DEs are set to auto-populate from Base Commit and also auto-populate from SOV in the payment business process (BP) standard line items, values from Base Commit take precedence for auto-population. Also, auto-populate from Base Commit or Change Commit takes precedence in payment line items if 0 or no value is provided through integration.
The Enable Step for Integration option in the Workflow BP setup is not available for the REST integration.
If provided, the BP Picker value must meet the configured query conditions. Otherwise, the system returns an Invalid value or multiple records found error.
The API prevents Create BP and Update BP operations from assigning Pull Down (drop-down) values that are marked as Inactive. This behavior matches the user interface (UI), where Inactive options are not shown or selectable. During Create BP Record and Update BP Record calls, the system validates the Pull Down values. If an Inactive option is supplied, the request is rejected, and the following message is returned: The value provided for <Data Element Label> has been set as Inactive and cannot be applied.

Uploading a File to a Document Picker DE

To upload a file as a value to a Document Picker DE, the following guidelines must be met:

Document Picker file must be included in the attachments ZIP file along with regular attachments.
The filename must be provided as the Document Picker DE value.
The corresponding file must be included in "_attachment", with "doc_picker_de" set to the Document Picker DE name.
If a Document Picker DE already has a file, its existing file is deleted and replaced.
Existing regular attachments, or existing Document Picker files attached as regular files, are ignored rather than revised.
The attachments without "doc_picker_de" are uploaded as regular attachments.
If Adding Attachment is disabled in the form and you attempt to attach a file to the corresponding form, the update succeeds if the request contains only Document Picker files. However, the update fails if the request contains at least one regular attachment.

If files from the Document Manager (DM) need to be attached, use the _attachment_from_dm field. Within that field, a comma-separated list of file IDs in the dm_file_ids field for the required DM files. You can attach up to 50 files from the DM at the record level and each line item level. Document-type and Text-type BPs are not supported.

Validate DM file attachments by confirming the following:

The integration user has DM permissions.
The string provided in dm_file_ids is a comma-separated list of file IDs.
The file IDs provided are valid.
No more than 50 files are attached from DM for the record or for each line item.
Example input field: "_attachment_from_dm":{"dm_file_ids":"123,345"}

Behavior of the Due Date (due_date) Field

When you update workflow BP records through a REST service, you cannot change the Due Date.

Response Format

A JSON object is returned in the following format.

{

"data": [],

"message": [],

"status": "<REST status code value>"

}

A successful response displays a status code 200.

A failed response displays a message with a status code.

Sample Request

{

"options":{

"project_number" : "P-0002",

"bpname":"line6",

"LineItemIdentifier":"upwoLISAS",

"optimizedPickerExecution" : "true",

"workflow_details":{

"WFCurrentStepName":"Step 4",

"WFActionName":"Line 3"

}

},

"data":[

{

"document_proof": "file_3.txt",

"ugenUserIDPK":null,

"_bp_lineitems":[

{

"ugenShellPK":"/AP1",

"uuu_tab_id":"Standard",

"short_desc":"desc3_m11",

"upwoLISAS":"0001",

"uuu_line_item_status":"Active",

"_attachment_from_dm": {

"dm_file_ids": "115"

}

],

"record_no":"uxli6-0020",

"title":"new title",

"_attachment":[

{

"file_name":"file_1.txt",

"title":"file_title1",

"issue_date":"05/06/2018",

"revision_no":"300"

},

{

"file_name": "file_2.txt",

"title":"file_title2",

"issue_date":"05/06/2018",

"revision_no":"200"

}

],

"file_name": "file_3.txt",

"title":"file_title3",

"issue_date":"05/06/2026",

"revision_no":"100",

"doc_picker_de": "document_proof"

}

],

"_attachment_from_dm": {

"dm_file_ids": "114"

}

],

"_attachment":

{

"zipped_file_name" : "zip_file_name.zip",

"zipped_file_size": "746089",

"zipped_file_content" :"<base64_encoded string of create.zip file>"

}

Adding LineItemIdentifier in the BP Design

To add LineItemIdentifier in the BP design:

Create a custom DE with DD: Sys Auto Sequence.
Add this DE to the Detail Form of the BP with the line items that need to be updated.
Go to the Company Workspace tab, and switch to Admin mode.
In the left Navigator, select uDesigner, and then select Business Processes.
Open the BP.
From the toolbar, select Open, and select Data Elements to open the Data Elements Configuration window.
Select the Auto Sequence tab, and select Add.
Select the data element added in the Detail Form and select the level as: Per Record.
Provide the start value and select Create.
Add the parameter "Sys Sequence counter" and select OK.
Select Integration, select Detail, and then add the DE.
Set the "Direction" to "Both" for that DE.
Complete and deploy the BP.
In the body of the request, add the DE name as Lineitem identifier and send the request.

Delete the Line-Item Using Update Request

To delete the line item using update request, the field "_delete_line_item" should be used (value of which will be comma separated values of LineItemIdentifier DE) as shown in the following example:

Sample: Delete line-item input

{

"options":{

"project_number" : "P-0002",

"bpname":"line6",

"LineItemIdentifier":"upwoLISAS"

},

"data":[

{

"ugenUserIDPK":null,

"_delete_bp_lineitems":"0002,0001,0003",

"record_no":"uxli6-0021",

"title":"title_m112244"

}

]

}

Sample Success Response

{

"data":[

],

"message":[

{

"_record_status":"success",

"record":{

"ugenUserIDPK":null,

"record_no":"uxli6-0021",

"title":"title_m112244"

}

],

"status":200

}

Sample Failed Response

If zip_file_size of uploaded zip file is not correct, a status code and message displays in the following format:

{

"data": [],

"message": [ "Uploaded Zip file is invalid" ],

"status": 3003

}

Data Elements in Line Items

If the following Data Elements are present in the Line Items, they will not be updated.

bitemid
budgetid
sovitemid
uuu_cm0_picker
xid
ds_code
fsm_lineitem_id
asm_lineitem_id
uuu_lat
uuu_long
uuu_company_account_name
uuu_company_account_code
uuu_company_acc_codepicker
uuu_activity_picker
uuu_asset_picker
ref_bpo_lineitem
ref_bpo
ref_rfb
refid
otherCompanyID
uuu_costcode_picker
scheduled_value
uuu_asset_cum_depreciation
uuu_asset_curr_period_dep
uuu_asset_net_book_value
uuu_unit_price
currencyid
due_date
uuu_asset_calc_as_of_date
uuu_from_date
uuu_issue_date
uuu_last_update_date
uuu_rfb_due_date
uuu_to_date
uuu_week_picker
uuu_datasource
uuu_depreciation_mtd
uuu_line_item_status
row_id
uuu_bid_count
uuu_bidders_count
uuu_planning_item_picker
uuu_proj_picker
record_no
uuu_resc_picker
uuu_role_picker
uuu_commit_short_desc
end_date
uuu_creation_date
uuu_asset_name
uuu_commit_breakdown
uuu_asset_code
uuu_asset_navigation_code
uuu_timescale_units
creator_id
wpid
uuu_cost_costattribute
uuu_cost_external_refid
uuu_cost_status
uuu_cost_cost_type
uuu_cost_description
uuu_cost_item
uuu_cost_owner
uuu_cost_code
uuu_dm_create_date
uuu_file_create_date
uuu_file_issue_date
uuu_dm_percent_complete
uuu_file_size
uuu_file_version
uuu_dm_description
uuu_dm_node_path
uuu_dm_node_name
uuu_file_revision_no
uuu_file_title
uuu_dm_create_by
uuu_file_create_by
uuu_fund_fundcategory
uuu_fund_long_desc
uuu_fund_description
uuu_fund_fundname
uuu_fund_code
uuu_description
uuu_resc_nwd_type
uuu_resc_interest
uuu_resc_proficiency
uuu_resc_skill
uuu_role_status
uuu_role_name
uuu_resc_capacity
uuu_user_address
uuu_user_city
uuu_user_country
uuu_user_email
uuu_user_fax
uuu_user_firstname
uuu_user_homephone
uuu_user_lastname
uuu_user_mobilephone
uuu_user_pager
uuu_user_state
uuu_user_timezone
uuu_user_title
uuu_user_workphone
uuu_user_zip
uuu_resc_status
uuu_resc_code
uuu_resc_name
uuu_early_finish
uuu_early_start,uuu_finish
uuu_late_finish
uuu_late_start
uuu_start
uuu_act_pct_complete
uuu_activity_work_hrs
uuu_duration
uuu_fixed_cost
uuu_float
uuu_labor_cost
uuu_non_labor_cost
uuu_total_cost
uuu_activity_id
uuu_flag_complete
uuu_flag_milestone
uuu_activity_resources
uuu_dependency_type
uuu_activity_name
uuu_outline_code
uuu_cost_li_type

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
		200	Success
	An exception occurs when the service is run.	500	Server Error, contact the system administrator.
`bpname`	BP name is invalid.	603	Business Process Name is not correct.
		650	Update Business Process failed reasons, files cannot be attached to upper form.
		650	Update Business Process failed reasons, files cannot be attached to detail form: <tab_name>
		650	Update Business Process failed as file(s) cannot be attached to line item. Add attachment from My Computer is not enabled for this Business Process.
		657	Invalid record_no.
		895	Record has already been accepted by Task Assignee.
	The required input JSON is empty.	1101	Empty or Invalid JSON data
	A partial failure of the service occurred.	3000	Partial failure.
		3002	Invalid Input
	When the ZIP file contains incorrect information	3003	Uploaded Zip file is invalid
	If user provides invalid file IDs for which there are no files in Document Manager	11001	File not found for file ID(s):
	If user tries to attach more than 50 files from Document Manager at either record or line item level	11003	No of files attached exceeds the allowed limit. Allowed limit: [50]
	If user tries to supply any value other than comma-separated numbers for the dm_file_ids field	11004	Invalid value for field dm_file_ids.
	If user tries to attach files from Document Manager for Text-Type BP	11005	Currently, Text Type BP is not supported for attachments from DM.
	Missing key or invalid user name		Enter a valid or an active user.
	Missing key or invalid/inactive workflow name		The workflow name is not valid.
	User is not an assignee on the creation step.		The user does not have an active workflow template.
	Missing key or invalid outgoing action name from creation step		The workflow action name is not valid.
			The value provided for <Data Element Label> has been set as Inactive and cannot be applied.