Solved

DOCMAN - Upload .png/.jpg file to IFS Cloud

  • 1 February 2022
  • 13 replies
  • 637 views
B
Rank
Badge +3

Hi,

 

I am currently working on a project to simulate a signature handling process relating to customer order deliveries.

 

The customer signs for a delivery which marks the order on the IFS Cloud 21r1 platform as delivered but I cannot use the MediaLibraryAttachmentHandling.svc and its end point [PATCH] /MediaItemSet(ItemId={x})

 

According to Fiddlers traffic logs ( and when a file is inserted via aurena’s UI ).

There is an extension of this endpoint ‘/MediaItemSet(ItemId={x})/MediaObject HTTP/1.1’ with RAW data being passed as binary format of a .png image. There is no JSON body being attached as per the IFS API documentation.

 

I am stuck at a point where I cannot understand how I can pass binary data in POSTMAN to this same endpoint. The API documentation isn’t providing any example other helpful instructions as to where the binary gets inserted so it can be passed to IFS’s database.

 

When I copy the application/octet-stream used from the fiddler data, IFS returns a not supported error message.

 

If I use the JSON body format as the documentation shows, what variable to do I pass the binary data into?

 

 

Thanks in advance,

 

Brian

 

 

icon

Best answer by Mathias Dahl 1 February 2022, 19:54

View original
This topic has been closed for comments

13 replies

Mathias Dahl
Rank
Userlevel 7
Badge +30

Hi Brian,

It’s hard to say what failed for you. I have recorded a small video on how you can see all the information you need to succeed with an upload (= PATCH) of your own.

In this case I used the Media Item page but you should be able to use Attachments / Media as well and see the same information (a PATCH will be done there as well).

In the recording I paused and selected some of the critical headers you need to set. These include the “if match” tag, the file name, which needs to be Base64 URL encoded (normal Base64 might work, but that depends on the data).

In general, this is how you can learn how to call ANY of our REST APIs in Aurena, with few exceptions. If Aurena can do it, you can do it from another tool, or script or a program.

Here is a link to the recording, let me know if you can view it:

https://ifs-my.sharepoint.com/:v:/g/personal/mathias_dahl_ifsworld_com/EYpcz3caWzpLnUShFtorP1cBtUwdkINRSv3crXPi2jebvA?e=MlhUPA

Good luck!

 

/Mathias
Mathias Dahl
Rank
Userlevel 7
Badge +30

To also answer one of your questions there:

I am stuck at a point where I cannot understand how I can pass binary data in POSTMAN to this same endpoint. The API documentation isn’t providing any example other helpful instructions as to where the binary gets inserted so it can be passed to IFS’s database.

The answer is that you should PATCH the data as raw bytes, and with NO other information as the “payload”. Different tools, languages and libraries has different ways to do it, and it might be named differently. You want to send the bytes only, plus some very important HTTP headers. I think the general information does not mention exactly how to send raw bytes, because of what I wrote above, it differs depending on the tool and I think the expectations are that if you want to do an “integration” like this, you are supposed to know how to use one of many of those tools that people use for these purposes.

You can get more help from the dev tools in Chrome. For example, you can get a ready-made script to run with different tools, like here:

 

/Mathias
B
Rank
Badge +3

Hi Mathias,

 

Thank you for your response, its greatly appreciated. After posting this topic I was able to resolve the issue which subsequently fixed the below API patch requests;

DocReferenceObjectAttachmentHandling.svc

MediaLibraryAttachmentHandling.svc

 

I was able to complete the patch request similar to your instructions;

x-ifs-content-disposition - Filename encoded to Base64 (used base64encode.org to get the result)

If-Match - eTag set following the format demonstrated in the video.

  • but the requirement for the ‘xsrf’ token was not needed for either usage.

 

A worth mention note, when using a GET request (POSTMAN) to retrieve all entries. The JSON object returns additional characters that needed removing (See example below).

W/"Vy8iQUFBU0o5QUJFQUFBemhVQUFBOjIwMjIwMjAxMTUxNjQ1Ig==" - is the correct entry for use in the If-Match parameter box.

Postman Header Variables

 

Using POSTMAN, providing the above parameters are set for the header request.

Attaching a document (valid filetypes for individual API’s) to POSTMAN’s request body as a binary object will allow the document to be filestreamed to the API’s endpoint.

 

The example explanation provided here uses the DocReferenceObjectAttachmentHandling.svc API.

 

MediaLibraryAttachmentHandling.svc uses the same process’s (eTag, application/octet-stream,Base64 encoded Filename) but uses different file types.

(The MediaLibrary does not allow .pdf documents to be patch requested by default)

 

Hope this helps the community,

 

Kind regards,

 

Brian

 

Mathias Dahl
Rank
Userlevel 7
Badge +30

Hi Brian,

Thanks for the update. I'm sure this will be useful to others.

I have a few comments:

Regarding the Base64 encoding, I want to emphasize that it should be "Base64 URL encoding", to be able to handle all scenarios. I learned this recently and have used "normal" Base64 encoding before with success. The scenario where that broke was also discussed here in the community. There they used Chinese characters in the file name. Not sure if that is relevant or not, but it revealed a flaw in using "normal" Base64 encoding at any rate. So, be warned. Now, if you never need to provide anything but a dummy file name (the extension must be correct though) you can hard code the encoded value, but if you need the file name to be different for each upload, you should use the right encoding.

but the requirement for the ‘xsrf’ token was not needed for either usage.

Thanks! I knew it is sometimes not needed and that it is sometimes needed, but I have forgot when.

About the etag value there, I suspect it is due to how PostMan visualize the value. If you would fetch the value using a program/with code and use that, I would not expect to have any problems. So I think you experienced a problem that only happens when you manually piece together a request. Good to know regardless though.

(The MediaLibrary does not allow .pdf documents to be patch requested by default)

Not only does media library not allow PDF files by default, it does not allow such files at all :)

Since you mentioned the DocReferenceObjectAttachmentHandling.svc API and apart from it not having tips for how to PATCH a binary/raw bytes, did you find the API documentation useful? (if you found it, that is)

Thanks!
 

/Mathias
B
Rank
Badge +3

The documentation was useful to piece together header variables and get the correct URI path but there is no additional instructions anywhere on IFS which helps users or developers understand the processes that Aurena uses to complete it’s action ‘under the hood’ so to speak.

 

At this moment in time, the PowerApp I am creating will still not complete the PATCH request when updating Media Items but I suspect this is due to encoding and conversion issues within the application and the stream becoming to long to pass with the request.

 

Does Docman only use octet-stream (binary) as an upload type? or is it possible to upload base64 encoded text as part of the PATCH request? If so, could you provide an example of where the base64 string would be inserted as part of the body request?

See below

{
  "Name": "It is a Text",
  "Description": "It is a Text",
  "MediaObject": "",
  "MediaText": "",
  "MediaThumb": "",
  "Obsolete": "It is a Text",
  "Resolution": "It is a Text",
  "MediaFile": "It is a Text",
  "MediaItemType": "Image",
  "PrivateMediaItem": "It is a Text",
  "Archived": true,
  "ArchiveNo": 1,
  "LatestAccessDate": "2019-10-10",
  "Repository": "Database"
}

 

Thanks in advance,

 

Brian

 

Mathias Dahl
Rank
Userlevel 7
Badge +30

Hi,

Thanks for your feedback. I will forward that reply to others who might know if there is any supporting documentation that would help here.

As for this:

Does Docman only use octet-stream (binary) as an upload type? or is it possible to upload base64 encoded text as part of the PATCH request?

Yes, we only work with binary data, both for upload and download, and both in Docman and Media Library. That is the best option as well since Base64 encoding and decoding adds overhead in the form of CPU time as well as network bandwidth (although that latter is probably small, when the traffic is compressed most of the time).

We could of course look into adding support for upload and download of Base64 encoded content, but the only reason to do so would be if there is some common tools that a lot of people use that cannot handle binary content, for some reason.

Thanks!

 

/Mathias
Mathias Dahl
Rank
Userlevel 7
Badge +30

PS. I would have loved to have a way to combine uploading a file/binary data with saving other metadata/attributes as well, but here we are limited with how the OData standard works.

It would be possible to add custom actions in our projections to handle both the file and the metadata but that would then be limited in how large files you can upload. As it is now, when the PATCH call is done separately (after creating the entity you want to upload the binary data to), we support files/content of “unlimited” (well...) size, and it is done in a streaming fashion that does not consume much memory.

 

/Mathias
B
Rank
Badge +3

Hi Again Mathias,

 

So, I have tried to complete a flow using the PATCH request for the MediaAttachmentHandling.svc

Attributes are dynamically added, and im pretty sure its just the raw data causing the internal server error but cannot be 100% certain as its running in PowerApps so fiddler cannot see the flow requests!

 

I have attached a snippet from my flow which uses PowerApps Pen Input.

PenInput encoded to JSON object,

24 Characters stripped from beginning and end of base64 encoded string so only the raw binary data remains.

Then converted via ‘base64tobinary’ function.

 

 

Any possible recommendations?

 

Thanks in advance,

 

Kind regards,

 

Brian

Mathias Dahl
Rank
Userlevel 7
Badge +30

Sorry, no…

I might be mistaken but, I think the body there, the binary content you want to PATCH, is not the reason for the problem. Why? Because the server should not care how that data looks like. Even if it would be “wrong” (you are encoding/decoding in the wrong way, for example), the server should accept it. Because, how could it know what binary data you want to upload?

So, my guess would be that, for some reason, the problem is in another part of the request.

By the way, what does it mean that it displays the MediaItemId there? Surely it cannot be part of the PATCH request. Does it become part of the URL you are PATCHing to?

 

/Mathias
B
Rank
Badge +3

The PATCH request requires the MediaItem’s ID to be able to attach the binary image to it, 

The MediaItem when created is referenced to a key reference (my project is using ORDER_NO={x})

See working postman request below;

The process used for this project follows a step by step tutorial for creating .jpg images using PenInput in power apps

 

 

I have tested the json object in a base 64 to image online converter and it displays correctly.

Using the video’s development process, created the image in one drive and downloaded it my device.

used that same image via the postman request (and it worked without issue!)

 

Im currently looking at using the document attachement handling .svc to see if the problem is only with the media attachment .svc and will feedback on the results, thank you for your help and guidance so far Mathias!

 

Kind regards,

 

Brian

Mathias Dahl
Rank
Userlevel 7
Badge +30

@BrianBloor Thanks for the update.

I guess my question stems from that I haven’t used PowerApps and I therefore don’t know the role of that dialog you added a screenshot of. What I want to say, again, is that, apart from the headers you cannot “patch” or “send” anything else than the binary content as part of the body. You could not, for example, include the media item ID (an OData restriction when uploading streaming content). That is why it is instead part of the URL, which is for some a subtle but still an important distinction.

I am out of ideas on why it does not work for you but I hope you will find the reason and the solution anyway.

Good luck!

 

/Mathias
B
Rank
Badge +3

Hi Mathias, 

 

Update on the situation, embarrased but successful….

 

The ‘==’ on the 64encoded file name where added via a concat statement in the power flow. 

 

Suggestion to any user exploring the same topic..

Check encoding of filename - does not need == to be deemed encoded 

(bad demonstration by youtube)

 

Removed them and all is good.

 

Thanks for your help

 

Kind regards,

 

Brian

Mathias Dahl
Rank
Userlevel 7
Badge +30

Hehe :)

The “==” we see in Base64 encoded text is just padding, which is sometimes there and sometimes not.

 

/Mathias
Terms & ConditionsCookie settings