Create BP Record with Attachment

POST /ws/rest/service/v2/bp/record/file

Available From: 19.11

Purpose

Create a record with attachments for the following types of business processes (BPs):

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

This REST service uses the Step form (Creation form) to create a BP record. All the required fields and validation rules run against the Creation form used in the workflow details.

For classic Payment Application and General Spends Change Commit detail lines that use a Dynamic Data Set (DDS) with the SOV Line Picker (uuu_sovlinum) in its behavior set, the REST service evaluates the DDS rule by using the master data element (DE) value for each line item in the request. If the rule makes the SOV Line Picker required, the request must include a valid SOV Line Picker value. If the rule disables the SOV Line Picker, the request must not include an SOV Line Picker value. If the rule is Disabled and Clear, Unifier clears the SOV Line Picker value and applies the disabled behavior. Requests that do not comply with the configured DDS behavior fail validation and return an error. This behavior is not supported for Summary Payment Application (SPA) Change Commit BPs.

Prerequisites

Ensure that the following items are in place:

  • Auto Creation settings are configured in the shell or company Setup for the Business Process (Admin mode).

    Note:

    During autocreation, if the value in a BP picker does not meet the filtering conditions that have been configured for the created BP, the picker value is not copied and remains blank. Additionally, in the Step form of the created BP, any data elements (DEs) that are configured to auto-populate from the picker are cleared.
  • For all BPs, select the Adding Attachment checkbox in the Upper Form or Detail Form.
  • 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. The input JSON provides various options for fetching data.

Note:

  • If Adding Attachment is disabled in the Upper Form or Detail Form and you try to attach file to the corresponding form, record creation succeeds if the request contains only Document Picker files. However, record creation fails if the request contains at least one regular attachment.
  • Only one record creation with attachments is supported in this call.
  • If the Creation form has Adding Attachment disabled, files are not attached.
  • If the "_attachment" field outside the data list for a ZIP file is not provided, the record is created without an attachment.
  • Field properties such as Read-only in the Step form (Creation 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.
  • 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.
  • If record_no is not provided, the system assigns an auto-generated record_no to the record. If you provide a unique record_no, the record is created with that value. If you use a record_no that is not unique, the system returns an error.
  • bpname is mandatory and is part of the options form parameter.
  • If workflow_details are not specified, the system uses the auto-creation settings defined in the BP setup.
  • If workflow_details are specified, the user_name, workflow_name, and action_name parameters are mandatory.
  • If DEs are set to auto-populate from Base Commit and also auto-populate from SOV in the payment 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.
  • If provided, the BP Picker value must meet the configured query conditions. Otherwise, the system returns an Invalid value or multiple records found error.

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.
  • 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, record creation succeeds if the request contains only Document Picker files. However, record creation 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

If the Override Workflow Due Date field is set to Yes for a workflow BP, when you create workflow BP records through a REST service, the Due Date provided in the input request is used.

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": "Vendors",

"workflow_details": {

"workflow_name": "workflow_name",

"user_name": "first_name last_name",

"action_name": "action_name"

}

},

"data": [

{

"title": "v-00101",

"document_proof": "file_3.txt",

"_bp_lineitems": [

{

"uuu_tab_id": "List of Contacts",

"title": "t",

"_attachment": [

{

"file_name": "new 1.txt",

"title": "file_title",

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

"revision_no": "100"

}

]

}

],

"_attachment": [

{

"file_name": "new 1.txt",

"title": "file_title1",

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

"revision_no": "300"

},

{

"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": "123,345"

}

}

],

"_attachment": {

"zipped_file_name": "create.zip",

"zipped_file_size": "746089",

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

}

}

Sample Success Response

{

"data": [],

"message": [

{

"uuu_user_id": "a@abc.com",

"uuu_record_last_update_date": "04-12-2018",

"uveFaxTB16": null,

"uveCertificateNoTB64": null,

"uvePrimaryContactTB64": "a",

"title": "v-00101",

"uveLicenseNoTB16": null,

"uuu_contact_company": "v-00101",

"_record_status": "success",

"uveCOIAmoutCA": 0,

"_bp_lineitems": [

{

"uirCntctFstNmTB": "a",

"uuu_user_workphone": null,

"uuu_tab_id": "List of Contacts",

"title": "t",

"ugenAddress1TXT120": null,

"_attachment_from_dm":{

"dm_file_ids":"456,789"

},

"_attachment": [

{

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

"revision_no": "100",

"file_name": "new 1.txt",

"title": "file_title"

}

],

"ugenAddress2TXT120": null,

"ugenCountryPD": null,

"ugenCityTXT50": null,

"short_desc": "Vendor Contact",

"uriCntctLstNmTB": "b",

"ugenStatePD": null,

"ugenZipCodeTXT16": null,

"uveEmailTB120": "hello@abc.com",

"ugenAddress3TXT120": null

}

],

"uvePolicyNoTB32": null,

"_attachment_from_dm":{

"dm_file_ids":"123,345"

},

"_attachment": [

{

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

"revision_no": "300",

"file_name": "new 1.txt",

"title": "file_title1"

},

{

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

"revision_no": "200",

"file_name": "exp1.txt",

"title": "file_title2"

},

{

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

"revision_no": "100",

"file_name": "file_3.txt",

"title": "file_title3",

"doc_picker_de": "document_proof"

}

],

"record_no": "VEN-0086",

"uveVendorTypePD": "Architect",

"ugenCityTXT50": null,

"uveCoiExpDOP": null,

"uuu_dm_publish_path": "v_path",

"uuu_contact_last_name": "b",

"ugenZipCodeTXT16": null,

"uveEmailTB120": "a@abc.com",

"ugenAddress3TXT120": null,

"uveReferenceIdTB16": null,

"uuu_creation_date": "04-12-2018",

"ugenRemarksTB4000": null,

"uvePhoneTB64": null,

"uveTaxIDTB16": null,

"uveMinorityBusCB": 0,

"uveInsuranceCoTB32": null,

"ugenExpirationDateDOP": null,

"uveWomanOwnedCB": 0,

"uveVendorNameTB50": "v-00101",

"ugenAddress1TXT120": null,

"uveDisadvantagedBusCB": 0,

"ugenDiscipline": null,

"creator_id": "Company Administrator",

"ugenAddress2TXT120": null,

"ugenCountryPD": null,

"uveVendorIDTB16": "v-00101",

"ugenStatePD": null,

"uuu_contact_first_name": "a",

"status": "Active",

"document_proof": "file_3.txt"

}

],

"status": 200

}

Sample Failed Response

{

"data": [],

"message": [

{

"_record_status": "Error Business Process record_no hello already exists. ",

"record": {

"uuu_user_id": "a@abc.com",

"uuu_record_last_update_date": "04-12-2018",

"uveFaxTB16": null,

"uveCertificateNoTB64": null,

"uvePrimaryContactTB64": "a",

"title": "v-00101",

"uveLicenseNoTB16": null,

"uuu_contact_company": "v-00101",

"uveCOIAmoutCA": 0,

"_bp_lineitems": [

{

"uirCntctFstNmTB": "a",

"uuu_user_workphone": null,

"uuu_tab_id": "List of Contacts",

"title": "t",

"ugenAddress1TXT120": null,

"ugenAddress2TXT120": null,

"ugenCountryPD": null,

"ugenCityTXT50": null,

"short_desc": "Vendor Contact",

"uriCntctLstNmTB": "b",

"ugenStatePD": null,

"ugenZipCodeTXT16": null,

"uveEmailTB120": "hello@abc.com",

"ugenAddress3TXT120": null

}

],

"uvePolicyNoTB32": null,

"record_no": "hello",

"_attachment_from_dm": {

"dm_file_ids": "115"

}

"_attachment": [

{

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

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

"file_name": "new 1.txt",

"title": "file_title1"

},

{

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

"revision_no": "200",

"file_name": "exp1.txt",

"title": "file_title2"

},

{

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

"revision_no": "100",

"file_name": "file_3.txt",

"title": "file_title3",

"doc_picker_de": "document_proof"

}

],

"uveVendorTypePD": "Architect",

"ugenCityTXT50": null,

"uveCoiExpDOP": null,

"uuu_dm_publish_path": "v_path",

"uuu_contact_last_name": "b",

"ugenZipCodeTXT16": null,

"uveEmailTB120": "a@abc.com",

"ugenAddress3TXT120": null,

"uveReferenceIdTB16": null,

"uuu_creation_date": "04-12-2018",

"ugenRemarksTB4000": null,

"uvePhoneTB64": null,

"uveTaxIDTB16": null,

"uveMinorityBusCB": 0,

"uveInsuranceCoTB32": null,

"ugenExpirationDateDOP": null,

"uveWomanOwnedCB": 0,

"uveVendorNameTB50": "v-00101",

"ugenAddress1TXT120": null,

"uveDisadvantagedBusCB": 0,

"ugenDiscipline": null,

"creator_id": "Company Administrator",

"ugenAddress2TXT120": null,

"ugenCountryPD": null,

"uveVendorIDTB16": "v-00101",

"ugenStatePD": null,

"uuu_contact_first_name": "a",

"status": "Active"

"document_proof": "file_3.txt"

}

}

],

"status": 3000

}

or if zip_file_size of uploaded zip file is not correct:

{

"data": [],

"message": [

"Uploaded Zip file is invalid"

],

"status": 3003

}

Validations

The following validations are performed:

  • If the user is a valid active user in the project.
  • The workflow name is valid and active.
  • User is an assignee (user/group) on the creation step of the workflow.
  • Action name is valid outgoing link from the creation step.
  • BP records will be created successfully:
    • If a single user with a specific First Name and Last Name exists in a project with a status of Active/On-hold.
    • If multiple users exist with identical First Name and Last Name, but only one user's status is Active/On-hold while all other users have an Inactive status.
  • BP records will not be created if multiple users exist with identical First Name and Last Name, with a status of Active/On-hold/Inactive.

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 Create Business Process failed reasons, files cannot be attached to upper form.
    650 Create Business Process failed reasons, files cannot be attached to detail form: <tab_name>
    650 Create 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.