iSheets API version 2 - iSheet module - API - iSheet item - edit
OVERVIEW
Method used to edit an iSheet item.
PUT
For the iSheet item ID : /api/3/isheet/{isheetid}/ items/{itemid}
For the external ID : /api/3/isheet/{isheetid}/ items/byexternalid/{externalid}
isheetid |
number |
The ID of the isheet |
itemid |
number |
The ID of the isheet item |
externalid |
String (A alpha-numeric value representing the ID of the item in an external system) | External system ID which is linked with an iSheet item ID. You can get the external ID from the get all isheet item api call. |
Request body
Send an iSheet item - Common Object - Add/Edit
Response
Case 1 : If the column data is incorrect the method returns a 403 http response for a un-successful request
<items>
<item>
<index>1</index>
<columns>
<column>
<columnid>1216</columnid>
<status>ERROR</status>
<statuscode>403</statuscode>
<message>#Name is required</message>
</column>
<column>
<columnid>1357</columnid>
<status>ERROR</status>
<statuscode>403</statuscode>
<message>#Invalid number for pincode</message>
</column>
</columns>
</item>
</items>
Case 2 : If the request is successful the columns will be added and the method returns a 200 http response
Natasha Miller-Santos one to speak to the development team about? CC Imran Aziz
Maarten Van.duijn I'm sorry that this has happened. We will raise a support ticket and ask the engineers if they can replicate this problem, and if so, to put it into our support queue to find a fix.
Maarten Van.duijn We still are encountering this issue, we get the following comment from one of our customers:
We noticed that when using this api to edit a record in an existing iSheet, the call is not accepted if a filter is placed in the default view for that iSheet. The response is 'access denied'. Removing the filter gets everything working again, but we need the filter on the view to prevent unedited rows to be seen by the enduser. Is there any solution/ way around this?
Hi Imran Aziz,
We suddenly experienced 'access denied' replies on iSheet edit calls.
{"summary":"Access denied"}
The only concurrent change was that the default view on that (files)iSheet was extended with a filter. All changes through the API call were blocked, regardless of any other priviliges or settings. Removing the filter on the view restored access to the API. Is it possible to have a filter on a view, and still edit the underlying iSheet records through the API? Thanks in advance, Maarten
You mentioned the XML export - if you are writing this client-side, then you can leverage JQuery to help filter out the @itemid.
For example, if results is string var containing the search results, then using the example I gave above:
// reusable helper function
function findFolder(params) {
return function(idx, el) {
return +$j(el)
.find("> column[attributecolumnid='" + params.columnId + "'] > rawdata folderid")
.text() === +params.folderId;
}
}
var itemId = $j(results)
.find("data > item")
.filter(findFolder({ folderId:1000, columnId:10000 }))
.attr("itemid");
// itemId will be undefined if folder not found in results...
if (itemId) {
itemId = +itemId; // convert string -> int
// ...
// ...
// ...
}
Thanks Andrew Quinn!
Andrew Quinn thank you for suggesting the work around and raising the issue with JSON response for iSheet search API, I will raise a bug for this issue. Thank you
Imran Aziz, as a side note: The iSheet search endpoint still only returns XML even if the request has an Accept header of application/json. Could you please add this to the backlog to have the endpoint JSON-enabled. Thanks in advance, Andrew
Even though there is no API for retrieving the folder metadata iSheet record, you can still achieve this now, until the official endpoint is developed that is:
- Create the folder as you currently do.
- Use the iSheet Advanced Search endpoint to search for the folder. You can only search by folder name, however, in the returned results will include the folder ID of the matching results which you can filter out to include only the folder ID you received from step #1.
IMPORTANT: Remember to encase your folder name in quotes ("My Folder Name") to find the exact matching folder, otherwise it's treated as ANY. - Once results are filtered, the iSheet record ID will be the @itemid attribute in the remaining
- .
Example of XML to submit to search endpoint, assuming the Folder column in my Folder iSheet is 10000:
<![CDATA["Engagement Strategy"]]>
Example of returned results for a simple Folder iSheet with one meta-data field:
<![CDATA[My Example Site]]>
<![CDATA[Folder]]>
<![CDATA[Default]]>
<![CDATA[Folder]]>
<![CDATA[Administrator Contact]]>
-
1000
<![CDATA[Engagement Strategy]]>
<![CDATA[2]]>
<![CDATA[Engagement Strategy]]>
https://instance.highq.com/instance/documentHome.action?metaData.siteID=9999&metaData.parentFolderID=999
1000
<![CDATA[Engagement Strategy]]>
<![CDATA[2]]>
<![CDATA[Engagement Strategy]]>
https://instance.highq.com/instance/documentHome.action?metaData.siteID=9999&metaData.parentFolderID=999
Hope this helps,
Andrew
Maarten Van.duijn thanks for the quick update, as I pointed out I am afraid we do not have a method to get the folder metadata iSheet ID, and I have escalated this requirement internally.
Thank you Imran Aziz,
The main issue is indeed the creation of a new folder, and adding metadata to its Isheet record. The other issue we can work around bij obtaining the information from the XML export (assuming the columnid's are persistent)
Regards,
Maarten
Maarten Van.duijn thank you for raising the questions. I am afraid we do not have an API at the moment to get the folder metadata iSheet and the requirement has been raised in our backlog.
Also, you can get the iSheet structure details using the iSheet admin functions as an admin user, however, a normal user cannot get the iSheet structure details. This improvement has also been placed in the backlog.
Let me discuss your use case with our technical team to find out if there is a workaround we can suggest and I will come back to you on that. Thanks
Hi Imran Aziz,
I am trying to add some metadata to files and folders that I create through the API.
The basic folder/file type Isheets seems tailored for that, but I am looking for a basic outline for this proces, and I have some questions.
This what I would like to do:
1. First create a folder through the API
2. Then obtain the Isheet record ID for that folder (How? Is there an equvalent of files/${fileid}/isheetRecordID?)
3. Create an edit object with the new values for my metatdata colums.
a. it needs column ID's, how can I obtain those?
b. Do I need to include elements for columns that I do not want to change?
4. I call /api/3/isheet/{isheetid}/items/{itemid}
Can you give me some pointers regarding these questions? Or outline a better process?
Thanks Maarten
Imran Aziz - thanks Imran (and devs) for the quick turnaround - much appreciated
Andrew Quinn the development team has resolved this issue in Collaborate 4.3.10, which should be available soon. Thanks
Andrew Quinn sorry about that, we will get it sorted.
Thanks, Imran Aziz. It's a strange one - that's 4 hours of my life St. Peter owes me Ù©(Í¡à¹Ì¯Í¡à¹)Û¶
Andrew Quinn thanks for raising the bug, I will raise the issue with our technical team.
Hi Imran Aziz,
There is a BUG with this endpoint:
No update actually occurs if; iSheet contains a Hyperlink column, and where there is a value in the record column, and the column wasn't provided in the update (PUT) request.
- Hyperlink field wasn't mandatory
- Create endpoint was fine
- Update (PUT) return code is 200 (Successful) but record unaffected
- Including Hyperlink value in Update (PUT) request results in record updated.
- Deleting Hyperlink field results in Update (PUT) updating record.
Basically, if you try updating an iSheet record without providing a hyperlink value (i.e. you're not wanting to update this column in the record), and the iSheet record already has a value, then no update occurs.
This is a high priority BUG for us, as it's effectively halted our project development.
Thanks in advance,
Andrew
Added the requirements to the backlog. Thanks Andrew Quinn
Thank for your comment Andrew Quinn and a good idea too. FYI - Imran Aziz
Hi Imran Aziz,
Working with the iSheet module API's, when creating/updating an iSheet item, I have a small problem with Choice columns. To set/update choice columns, in the iSheet item, I need to supply the choice ID (as described in this wiki) which requires a prior call to the get columns end point. The complication is that this is an admin function which means access will be restricted to admin auth. tokens. So, we would need to have a prior workflow that, using an admin token, retrieves the choice list items which can be used later (by the create/update iSheet item workflow). What's needed is a suite of non-admin API calls that can:
1. get iSheet details, for a site, that the user has access to
2. get iSheet View details, for a site + sheet, that the user has access to
3. get Column details, for a site + sheet, that the user has access to
In effect, opening up the 'get' methods of the admin functions - as long as the user has access to these entities (site/sheet/view/column).
Thanks, Andrew
Comments
21 Comments