Menu

Service Help – EntryFormPost

The Sharperlight service offers a wide variety of presentation methods, each with its own set of parameters.

In this post, we will introduce the following method from among the various presentation methods available.

http://abcd.com/mdService1Rest/EntryFormPost/…

EntryFormPost
To see this information with your sharperlight service help
{sharperlight service url}/Help#EntryFormPost
There are various ways one can use POST when process one or many records on the same table or different tables.
When just using the default settings the POST will validate and commit the data but you may want to have finer control over this process to avoid half committed data when using batches.
Batch POSTs allow you to process data more than one Table in the same or even different Products.
You can set a Transaction ID to enable with the rollback of the data in the case of errors.
It is also possible to do a validation only POST in case your backend system cannot support a database rollback (See options parameter)


Remember you can use the main Web Channel Index Page and Data Entry / Tree to browse the writeback tables for their Data Entry Forms, Grids and POST metadata and Javascript templates
Writeback Table Metadata


SETTING RECORD VALUES

The POST data takes the same format as a URL address with various parameters and their values for example &ipf0=Computer%20Software
The record fields can be set in two different ways.

1) Field Orginal Position ipf(0..(n)) – Set by ordinal position in writeback field list e.g &ipf3=Company%20ABC
2) Field Unique Code Path ipc:\(code)- Set by field’s unique code path in writeback field list e.g. &ipc:\CompanyName=Company%20ABC

Remember you can query any Writeback Table’s Metadata to find all the codes and other attributes by using the System \ Datamodel Writeback Metadata table.


SETTING THE PRODUCT AND TABLES

Set the default &productcode=, &supercode= ,&tablecode= and when required the &usid=(User Session ID) on the URL address
You can override the default productcode, supercode and tablecode by setting the &productcode=, &supercode= or &tablecode= inside the POST data on the desired record


EXAMPLE USING ORDINAL ipf(n)=value

http://abcd.com/mdService1Rest/EntryFormPost?productcode=SLPO&tablecode=PriceList
ipf0=X1000&ipf1=Widgets+Big+Box&ipf2=7.45&ipf3=2018-06-01

EXAMPLE USING CODE PATH ipc:\(code)=value

http://abcd.com/mdService1Rest/EntryFormPost?productcode=SLPO&tablecode=PriceList
ipc:\Code=X1000&ipc:\Name=Widgets+Big+Box&ipc:\Price=7.45&ipc:\UpdateDate=2018-06-01

EXAMPLE WITH MANY RECORDS TO THE SAME TABLE

http://abcd.com/mdService1Rest/EntryFormPost?productcode=SLPO&tablecode=PriceList
wbBatchMode=1&ipc:\Code=X1000&ipc:\Name=Widgets+Big+Box&ipc:\Price=7.45&ipc:\UpdateDate=2018-06-01
&wbBatchMode=2&ipc:\Code=X2000&ipc:\Name=Widgets+Medium+Box&ipc:\Price=3.45&ipc:\UpdateDate=2018-06-01
&wbBatchMode=3&ipc:\Code=X3000&ipc:\Name=Widgets+Small+Box&ipc:\Price=1.45&ipc:\UpdateDate=2018-06-01

EXAMPLE WITH MANY RECORDS TO DIFFERENT TABLES (HEADER/LINES) WITH TRANSACTION ID

http://abcd.com/mdService1Rest/EntryFormPost?productcode=SLPO
wbBatchMode=1&wbBatchTrans=MyID&tablecode=POHeader&ipc:\PONo=PO00125&ipc:\ClientCode=CL00123&ipc:\OrderDate=2018-06-01&ipc:\DeliveryDate=2018-06-12
&wbBatchMode=2&wbBatchTrans=MyID&tablecode=POLine&ipc:\PONo=PO00125&ipc:\ItemCode=X1000&ipc:\Qty=1
&wbBatchMode=3&wbBatchTrans=MyID&tablecode=POLine&ipc:\PONo=PO00125&ipc:\ItemCode=X2000&ipc:\Qty=5


USER SESSION

The user session id is not required if the user has already signed on and a cookie session is active or the Service is using NTLM (Windows Single Sign On)
If NTLM is not enabled make sure user session is is always set on the URL address &usid=4a9c02409432477b99066bcbafe35195Z
EXAMPLE USER SESSION &usid=

http://abcd.com/mdService1Rest/EntryFormPost?productcode=SLPO&tablecode=PriceList&usid=4a9c02409432477b99066bcbafe35195Z
ipc:\Code=X1000&ipc:\Name=Widgets+Big+Box&ipc:\Price=7.45&ipc:\UpdateDate=2018-06-01


STATUS

The POST results are returned in a JSON Status object with contains a high level summary of any errors and a array of details errors or feedback if present.
Use the response and callback parameters to control the type of status returned. e.g &response=json&callback=MyFunc will do a JSON callback

message: Generally blank if successful but it writebacks may set this on special occasions as a kind of notice or feedback
recordsAffected: The number of rows affected is returned when successful
recordId: The database row Identity of the new record inserted when posting just one record and it was inserted not updated
historyId: The Row ID of the record created in Writeback history which contains all the stats and status of the writeback which includes if it’s still running, finished has errors
Writeback History is enabled in Site Setup. When enabled it is useful for situations very large POST payloads require a lot of time to process and you want to check the results
at a later time or on another web page. Using the history Id one can query the System / Writeback / History table to know if the writeback was OK, ERROR or RUNNING.
There is a field that holds the response in JSON format. It contains details of how many records were affected and if there were any errors etc.
statusCount: If there are errors it is set to the Count of the statusList.status[] array. When 0 there will be no status array
status.field: The field ordinal position in the writeback list e.g field:”ipf3″
status.fieldCode: The field unique code in the writeback list e.g fieldCode:”\Qty”
status.tableCode: The table unique code of the field e.g fieldCode:”POLine”
status.batchNo: The batch mode number if set where the error was found e.g batchNo:2 1..(n)
status.recordIndex: The record index. If writing to a single table this will be the row Index 0..(n) e.g recordIndex:2
status.category: The error category which case be any of the following InvalidValue, Permissions, InternalError
status.message: The error message e.g message:”Invalid custom code XX11″


Successful POST with no errors

{
“message”:”” ,”recordsAffected”:1 ,”recordId”:-1 ,”statusCount”:0 ,”errorMessage”:””
,”status”: [ { “field”:””, “fieldCode”:””, “tableCode”:””, “recordIndex”:0, “batchNo”:0 , “message”:””} ]
}

Unsuccessful POST with errors

{
“message”:””
,”recordsAffected”:2
,”recordId”:-1
,”statusCount”:3
,”errorMessage”:”Please correct the errors and resubmit.”
,”status”: [
{ “field”: “ipf3”, “fieldCode”: “\OrderDate”, “tableCode”: “POHeader”, “batchNo”: 1, “recordIndex”: 0, “category”: “InvalidValue”, “message”: “Invalid Order Date” }
,{ “field”: “ipf2”, “fieldCode”: “\Qty”, “tableCode”: “POLine”, “batchNo”: 2, “recordIndex”: 0, “category”: “InvalidValue”, “message”: “Invalid Number A123” }
,{ “field”: “ipf1”, “fieldCode”: “\ItemCode”, “tableCode”: “POLine”, “batchNo”: 3, “recordIndex”: 0, “category”: “InvalidValue”, “message”: “Invalid Item Code X9999” }
]
}


BATCH MODE

To POST multiple table writebacks take the format explained above and put wbBatchMode=(1..n) on the front of each record in the POST data.
If the target product supports database transactions and rollbacks then you can set transaction IDs by adding &wbBatchTrans=MyUniqueID
Transaction ID’s are very useful when you want to rollback all the changes as one block if there is some sort of error
In version 4.7 it was 1,000 rows, 4.8 was 10,000 rows and version 5.0.20 onwards it is 1 million rows

http://abcd.com/mdService1Rest/EntryFormPost?productcode=SLPO&wbBatchTrans=ID001
wbBatchMode=1&tablecode=POHeader&ipc:\PONo=PO00125&ipc:\ClientCode=CL00123&ipc:\OrderDate=2018-06-01&ipc:\DeliveryDate=2018-06-12
&wbBatchMode=2&tablecode=POLine&ipc:\PONo=PO00125&ipc:\ItemCode=X1000&ipc:\Qty=1
&wbBatchMode=3&tablecode=POLine&ipc:\PONo=PO00125&ipc:\ItemCode=X2000&ipc:\Qty=5
&wbBatchMode=4&tablecode=POHeader&ipc:\PONo=PO00126&ipc:\ClientCode=CL00123&ipc:\OrderDate=2018-06-01&ipc:\DeliveryDate=2018-06-15
&wbBatchMode=5&tablecode=POLine&ipc:\PONo=PO00126&ipc:\ItemCode=X3000&ipc:\Qty=4
&wbBatchMode=6&tablecode=POLine&ipc:\PONo=PO00126&ipc:\ItemCode=X2000&ipc:\Qty=1

Multiple Transactiond ID’s with different Products

http://abcd.com/mdService1Rest/EntryFormPost?productcode=SLPO
wbBatchMode=1&wbBatchTrans=ID001&tablecode=POHeader&ipc:\PONo=PO00125&ipc:\ClientCode=CL00123&ipc:\OrderDate=2018-06-01&ipc:\DeliveryDate=2018-06-12
&wbBatchMode=2&wbBatchTrans=ID001&tablecode=POLine&ipc:\PONo=PO00125&ipc:\ItemCode=X1000&ipc:\Qty=1
&wbBatchMode=3&wbBatchTrans=ID001&tablecode=POLine&ipc:\PONo=PO00125&ipc:\ItemCode=X2000&ipc:\Qty=5
&wbBatchMode=4&wbBatchTrans=ID002&tablecode=POHeader&ipc:\PONo=PO00126&ipc:\ClientCode=CL00123&ipc:\OrderDate=2018-06-01&ipc:\DeliveryDate=2018-06-15
&wbBatchMode=5&wbBatchTrans=ID002&tablecode=POLine&ipc:\PONo=PO00126&ipc:\ItemCode=X3000&ipc:\Qty=4
&wbBatchMode=6&wbBatchTrans=ID002&tablecode=POLine&ipc:\PONo=PO00126&ipc:\ItemCode=X2000&ipc:\Qty=1
&wbBatchMode=7&productcode=BUDX&tablecode=Audit&ipc:\PONo=PO00126&ipc:\AuditDate=2018-06-01
wbBatchMode=1&productcode=ADVW&tablecode=Department&ipf0=…&wbBatchMode=2&productcode=ADVW&….&wbBatchMode=3&&productcode=ADVW….
or with Transaction IDs
wbBatchMode=1&wbBatchTrans=MyID&productcode=ADVW&tablecode=Department&ipf0=…&wbBatchMode=2&wbBatchTrans=MyID&productcode=ADVW&….&wbBatchMode=3&wbBatchTrans=MyID&productcode=ADVW….

If the product is omitted the it is assumed that all data is for the Product defined on the URL address. If the tablecode is omitted then it’s assumed that all the data is for the same table defined on the URL address.

Be careful when setting the transaction ID &wbBatchTrans=XXXX
Generaly you would not set it at all or set them all to be the same ID. If is possible to leave blank when not required and set blocks of ID’s where required.
If you were posting Header and Line records and wanted to be rolled back the whole post if something was invaid, then give them all the same transaction ID as a block
It is possible to Post to different Products but one should never share the same transaction ID across Products.
Sometimes the target Product is using an API and cannot support Transaction ID’s, so keep this in mind
Note that if you are Posting many records to the same table then Transaction ID’s are not required.
There is a limit of 10000 rows for a single post.

OPTIONS

Validate Validate only mode &options=Validate
Update The default is already update &options=Update
Delete Delete the records based on their unique field or fields in the rows data &options=Delete
DeleteKey Delete the records based on just the unique field key. No need to set all the data &options=DeleteKey
BreakOnFirstRowError Break on the first row error when processing &options=Update,BreakOnFirstRowError
NoBreakOnRowError Do not break on the first row error when processing &options=Validate,NoBreakOnRowError
BatchValidateBeforeCommit This is the default when processing batches this will ensure that all batch data is validated before going to the commit processing stage.
&options=Update,NoBreakOnRowError,BatchValidateBeforeCommit
BatchValidateDuringCommit When processing batches you may want to speed up the process and skip the up front validation step and just do with batch by batch validation and commit.
This means however if 3 batches are processed and then their is a failure and your not using transaction IDs for rollback, then the remaining batches will not be committed



ENCRYPTION

Sharperlight Data Entry Forms will always Tripple DES encrypt the POST data just in case https/SSL has not ben setup.
It is possible to also do this but normally you would just setup https/SSL to take care of this.
However you can still Tripple DES protect the POST data by viewing the javascript of an EntryForm to get an idea of how to post data and process the return status
Basically the POST data is tribble DES encrypted and a special header is set e.g. DES0x6b68ea21f..ff

The buffer that is encrypted would look something like a url param list where ipf0 to ipf(n) are the field indexes and ipf2 would be the third field in the Entry Form
productcode=[product] DataModel Product Code e.g. productcode=ADVW
supercode=[value] If the Product has a super field (optional) that is filtered before the Tables, then set it here. e.g. supercode=CompanyID
tablecode=[tableCode] DataModel Product Table Code e.g. tablecode=ProLoc
ipf0=[value] First Field’s value. format: dates as yyyy-mm-dd HH:mm:ss boolean as 0 or 1 and Values list should be set to their code or description
ipf#=[value] Set the value of the Field by it’s Field No position e.g. &ipf3=ABC%20Software
ipc:(code)=[value] Set the value of the Field by it’s unique code path (Use the System Datamodel Writeback Metadata Table to get codes) e.g. &ipc:\CompanyName=ABC%20Software
usid=[sessionid] User Session ID
options=[comma,list] Writeback options separated by a comma [Validate,Update,Delete,DeleteKeys,BreakOnFirstRowError,NoBreakOnRowError,BatchValidateBeforeCommit,BatchValidateDuringCommit]
When options are left blank the default behaviour will be to validate all then commit for non-batch Posts and validate while processing batch records in batch mode

For batch mode POST you may want to first post with &options=Validate so just validation is done.
Then follow with another POST with &options=Update or no options to actually do the commit. Note this POST still does validation and committing but at the batch level.

If you want to do just one POST when dealing with batchs but require a complete up front validation before going to the commit phase then use &options=BatchValidateBeforeCommit
uniqueID=[uniqueHash] To prevent the page being cached create unique value say on the date time e.g. uniqueID=D5H16M43S0D
response=[json|jsonp] When left blank the status response will be
{ message: ……}

When set to json it will be
{ message: ……}

When set to jsonp it will be unless you set callback
Callback( { message: ……} );
callback=[MyFunc] JSON Callback function (Optional) &callback=MyFunc results in MyFunc { “message”: ……} );
Sharperlight Service Help Top

Related Posts