Skip to Content
Product Information
Author's profile photo Deepak G Deshpande

SAP Cloud Integration – Swagger/OpenAPI Spec JSON in Message Mapping

Introduction

SAP Cloud Integration version 3.30.**/ 4.17.** comes with an enhancements/feature for message mapping where in you can upload and map the Swagger/Open API Spec JSON file. This blog describes about this new enhancement.

Swagger/Open API Spec JSON

When we say Swagger/Open API Spec JSON, we are supporting the JSON files based on OpenAPI Spec 2.0 and 3.0 version and especially the JSON definition files of the REST APIs hosted on https://api.sap.com . For a given REST API, you can download the definition file of the same as shown in the screenshot below. Here a JSON specification file of an Ariba REST API is used.

Ariba%20Asset%20Management%20API%20on%20SAP%20API%20Hub

Ariba Asset Management API on SAP API Hub

 

Click%20on%20Download%20API%20Specification%20JSON

Click on Download API Specification -> JSON

 

JSON%20File%20Downloaded

JSON File Downloaded

Once you download the Swagger JSON, you can use it in your message mapping. To use this feature, you need Message Mapping flow step version 1.1. When you drag and drop the message mapping flow step of the said SAP Cloud Integration version, it will be of the latest one, i.e. version 1.1.

Below are the screenshot on how to see a flow step version.

Click%20on%20%28i%29%20icon

Click on (i) icon

Version%20number%20of%20the%20flow%20step

Version number of the flow step

 

 

You can upload this JSON file similar to other currently supported XSD, WSDL or EDMX file. Just click on source OR target part of the message mapping an upload it. Below sequence of screenshots shows the different UI screens you see once you select and upload the swagger JSON file.

Adding%20Message%20Mapping%20Flow%20step%20after%20click%20%28+%29%20on%20Content%20Modifier

Search and add Message Mapping Flow step after click (+) on Content Modifier

 

Click%20on%20Create%20icon/speed%20button

Click on Create icon/speed button

 

Provide%20a%20name%20for%20the%20message%20mapping

Provide a name for the message mapping

 

Mapping%20Editor%20Opens%20up%20Add%20Source

Mapping Editor Opens up -> Add source message

 

Upload%20the%20downloaded%20JSON%20file

Upload the downloaded JSON file

 

 

Select%20API%20Path

Select API Path

 

 

 

 

Source%20structure%20in%20Mapping

Source structure in Mapping

 

Upload%20the%20target%20structure%20as%20well%20and%20define%20mapping

Upload the target structure and define mapping

 

All the standard functions, along with Groovy script based custom functions/user defined functions (UDFs) of the mapping expression editor are supported for the uploaded swagger JSON. You can use these functions for your mapping definition needs.

You can upload other supported file as well in combination with JSON. That is, JSON file at the source side and a WSDL file at the target side (or vice versa) of the message mapping as per your integration scenario needs.

Further, you can complete the message mapping and/or integration flow development as usual and deploy, run the integration scenario.

Planned Enhancements

Below topics are planned for the future enhancements.

JSON Schema as per https://json-schema.org/

As of now, only swagger JSON files are supported, and going forward we will be working on the provide the support for JSON files which adhere to the specifications as defined in https://json-schema.org/. This shall come handy when you have a JSON structure for other kind/third party systems of integrations which understands JSON data files/payloads adhering to said spec.

 

Multi Mapping

Currently, the Swagger JSON is not supported in multi mapping. In feature increments we will be working on to enable it.

 

Summary

Support of swagger JSON will now enable you to develop the integration scenarios, which probably pure JSON based scenarios communicating with REST APIs without the need of JSON <-> XML converter steps which were previously mandatorily required because message mappings were able to only understand XML payloads. Now can you avoid JSON <-> XML converter steps for such scenarios.

Assigned Tags

      40 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Santhosh Kumar Vellingiri
      Santhosh Kumar Vellingiri

      Hi Deepak,

      Great to see native support of JSON in Message mapping.

      Is there also a plan to provide message validation based on OAS? I think that will be very helpful too.

      Thanks,
      Santhosh.

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi Santhosh,

      Thanks for the input.

      Can you elaborate about your expectation with "provide message validation", and OAS I assume that you are using short form of OpenAPI Specification.

       

      This will help me answering your query.

       

      Thanks

      Deepak

      Author's profile photo Santhosh Kumar Vellingiri
      Santhosh Kumar Vellingiri

      Hi Deepak,

      Yes. I was referring to Open API Specification and validating the inbound JSON message payload schematically to it.

      Thanks,
      Santhosh.

      Author's profile photo Raffael Herrmann
      Raffael Herrmann

      Hi Deepak,

      these are great news! Really looking forward to get the new functions pushed to our tenant.

      One question: How do the mappings work "under the hood". Have you implemented a native JSON mapping engine or will JSON payloads internally, automatically converted to XML and then handled by the current/classic CPI/PI mapping engine?

      Background: I'm asking this because I fear unexpected outcomes, in case there would be a silent JSON-to-XML conversion instead of a JSON native engine.

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi Raffael,

      Thanks for the feedback.

      When the JSON file is uploaded, it is used and represented in SAP's message mapping (MMAP) format (equivalent to your statement of >> current/classic CPI/PI mapping engine<<).

      We aren't doing any conversion to XML again.

      Due to direct interpretation in MMAP, we were able to provide standard + groovy script based custom functions support, display queue and mapping simulation support in the first release iteration of JSON support in message mapping.

       

      Thanks

      Deepak

      Author's profile photo Alexey Palagin
      Alexey Palagin

      Thank you for sharing this, I am sure it will be a useful feature. We're still on 3.29. Is there a way to see all new features in the upcoming release?

      Thank you.

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi Alexey,

      There will be a blog written on 2020 release cycles. Once available, I will share with you.

      For 3.30.**, the planned customer release is on or after 24th Oct 2020. I will update you in case of any deviations.

       

      Thanks

      Deepak

      Author's profile photo Alexey Palagin
      Alexey Palagin

      Thank you very much for the update, Deepak.

      Author's profile photo Syambabu Allu
      Syambabu Allu

      Nice one.Thanks for sharing!

      Author's profile photo Apu Das
      Apu Das

      Hi Deepak,

      This is great.

      Is the any roadmap to support RAML in future?

       

      Thanks,

      Apu

      Author's profile photo Sven Huberti
      Sven Huberti

      Hi Apu,

      my 2 cents here: as far as I can see from my customers, RAML has seen very poor adoption. I just checked against Google Trends too:

      https://trends.google.de/trends/explore?date=all&q=raml,openapi,swagger

      So my guess (I am not involved in product management) is that we will not have native support for RAML. But you can still use open source or web tools to transform your RAML into OpenAPI. We also feature that in SAP API Management, in the API Designer (API Portal/Develop/API Designer/Paste/Raml).

      BR!

      Sven

       

      Author's profile photo Raffael Herrmann
      Raffael Herrmann

      Hi Deepak G Deshpande ,

      was there recently a change in the API Hub or the mapping engine? When trying to import the API definitions for Cloud Platform Integration (https://api.sap.com/api/IntegrationContent/overview --> Details --> Download API specification --> "JSON") the CPI shows an error.

      When checking the JSON spec in an online validator (https://apitools.dev/swagger-parser/online/) we can see that the specifications are not longer valid...

      Is this a known bug or did the API move to an incompatible spec format?

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi Raffael,

      From SAP Cloud Integration/mapping engine perspective, there are not changes, I need to check with respective SAP API Hub team for any recent changes.

      And was the JSON file  (https://api.sap.com/api/IntegrationContent/overview --> Details --> Download API specification --> "JSON"), working before at your end and now stopped working?  Please let me know.

       

      Thanks

      Deepak

      Author's profile photo Raffael Herrmann
      Raffael Herrmann

      Hi Deepak,

      I haven't tried to import this specific API spec before, so I can't say if it worked in the past. But while cross-checking with the API spec you pointed out in your article, it seems like yours is fine and only the CPI spec is broken...

      I tried to find the point that breaks during validation and for me it looks like the API spec delivered by API hub is broken/incosistent:

      As you can see in some points of the specification the parameters are defined as type "query" instead of "path", but the URL pattern itself points out {id} curly braces (which are meant to be used for path paramters). So either the url patterns are defined incorrect or the parameter type should be switched to path.

      Whom to inform about such kind of errors?

      Author's profile photo Raffael Herrmann
      Raffael Herrmann

      Hi Deepak G Deshpande ,

      I managed to manually fix the JSON spec downloaded from API hub. (Corrected the path/urls only.) After that the import into CPI was successful. Unfortunately it seems like I have found a bug (?) in the mapping editor, now.

      The API spec downloaded from API hub provides the following type definition:

      But when imported into CPI the following type is generated:

      Where are the other fields (like Vendor, Version, etc.) of the datatype definition? From my understanding they should have been generated, too. (Even if they can be null by definition, they should part of the mapping datatype.)

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi Raffael,

      Thanks for the updates on this. I am checking with API hub team on validation issues after downloading the file.

      Meanwhile, as you have corrected the error manually, that would be the way to fix it as of now. And for Version and Vendor are not listed because it has the type array with string and null values. Can you remove the array declaration and just manually correct it to have type:string (similar to line number 5026 in your screenshot) ? That should unblock you.

       

      Thanks

      Deepak

      Author's profile photo Raffael Herrmann
      Raffael Herrmann

      Hi Deepak,

      you're right - removing the null values/array and switching to string type, make the fields visible in the mapping editor.

      Nevertheless, I think either the mapping editor should be more robust or the JSON specs from API hub should be cleaned. Because right now it's a really disappointing experience. If one has to manually fix multiple fields/parts of the spec, many advantages of the harmonious interaction between api hub and cpi are lost. For me it's ok, but I guess there may be others that remain on the sidelines.

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi Raffael,

      Thanks for the feedback, and yes, we are making adjustments in mapping to handle such types gracefully and reduce the user's manual efforts in fixing them in the downloaded JSON.

       

      Thanks

      Deepak

      Author's profile photo Said Moshref
      Said Moshref

      Hi Deepak,

      awesome blog!

      In our project is use the swagger schema for mapping.

      In the schema i defined a type "boolean" but unfortunately the result of the message is a string.

      I would expect a true but get a "true".

      Do i make something wrong?

      Schema:

      "prefered_vendor": {
      "type": "boolean"
      }

      Best Regards,

       

      Said

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi Said,

      We cross-checked internally and found the value to be true and not "true", can you share your schema file along with element details such that we can check?

       

      Thanks

      Deepak

      Author's profile photo Said Moshref
      Said Moshref

      Hi Deepak,

       

      sure, It's an excerpt of a POST operation.

      "post": {
      "parameters": [],
      "responses": {
      "200": {
      "description": "Success",
      "content": {
      "application/json": {
      "schema": {
      "properties": {
      "success": {
      "type": "boolean"
      }
      },
      "additionalProperties": false,
      "required": [
      "success"
      ],
      "type": "object"
      }
      }
      }
      }
      },
      "requestBody": {
      "description": "Input JSON Structure",
      "content": {
      "application/json": {
      "schema": {
      "properties": {
      "inforecord": {
      "properties": {
      "vendor_id": {
      "type": "string",
      "maxLength": 10,
      "example": "113"
      },
      "article_id": {
      "type": "string",
      "maxLength": 40,
      "example": "94544320"
      },
      "prefered_vendor": {
      "type": "boolean"
      }
      },
      "additionalProperties": false,
      "required": [
      "vendor_id",
      "article_id",
      "prefered_vendor"
      ],
      "type": "object"
      }
      },
      "additionalProperties": false,
      "required": [
      "inforecord"
      ],
      "type": "object"
      }
      }
      }
      },
      "summary": "info_record",
      "description": "Create a new info record"
      }

       

      Mapping%20Rule

      Mapping Rule

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi Said,

      Sorry for the late reply, I have asked my team to look into this. I will update you.

       

      Thanks

      Deepak

      Author's profile photo Romain LESEVE
      Romain LESEVE

      Hi Deepak,

      Very nice blog, thank you very much !!!

      I want to extract p-user from BTP to an Hana database.

      I use SAP API Identity Directory Service (https://api.sap.com/api/IdDS_SCIM/overview) to extract this user list.

      I follow your blog to fill my message mapping but when I choose my JSON file (downloaded from URL above), no API is available :

      I try to update {tenant} into the JSON file with my own tenant but it doesn't work.

      Did I forget something ?

       

      Thanks again,

       

      Romain.

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi Romain,

      You still face the issue? If so, can you share the JSON file if possible?

       

      Thanks

      Deepak

      Author's profile photo Allen Chew
      Allen Chew

      Great blog. Beginning to love this feature where OpenAPI spec is awesome. Now we can perform JSON-to-JSON mapping and write API documentation at the same time.

      Author's profile photo Dinesh M
      Dinesh M

      Hi Deepak,

      First i must thank you for introducing me to such an API

      I had a doubt whether JSON conversion is possible in message mapping and i got your blog.

      I am writing this to clarify one query, I had followed the same steps as mentioned in the blog,

      1.Downloaded the Schema from Ariba Management API

      2.Loaded in CPI Resource

      3.Did one-to-one message mapping

      Now the issue is I'm getting blank json as output eventhough input file contains all the values(sample input also taken from Test view in Ariba API. Could you let me know what could be the issue?

       

       

      Thanks,

      Dinesh

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi Dinesh,

      I would request you to raise a ticket, which details on the Ariba Management API JSON file, and sample input which wish to test, relevant teams would look into the issue and provide response.

       

      Thanks

      Deepak

      Author's profile photo Philippe Addor
      Philippe Addor

      Hi Deepak

      That would be a great feature! Unfortunately, as far as I can see, it is currently broken. No matter which JSON file I download from the API hub, I get "This file has validation errors" when trying to link it in the mapping editor. There is no further error information. I'm on a Trial tenant.

      Is it still supposed to work?

      Update: I found one working json (SAP Action Events). But the ones for Amazon S3 and Azure Blob are not working. The structure looks indeed a bit different. But according to a validator, bot cases are actually valid. So I think the function needs to be improved to be able to parse both types of OpenAPI JSON files from the API Hub.  

      Best,

      Philippe

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi Philippe,

      Thanks for the comment, can you share a sample JSON file where you faced issue? I will check with my team

       

      Thanks

      Deepak

      Author's profile photo Philippe Addor
      Philippe Addor

      I was trying with the JSON file downloaded from here: https://api.sap.com/api/amazons3/overview

      Thank you,

      Philippe

      Author's profile photo Jan Curinckx
      Jan Curinckx

      Hi Deepak,

       

      Thanks for the nice blog. It allowed me to create an XML to JSON and JSON to JSON mapping.

       

      What I noticed however is a difference in behaviour.

       

      When I use the JSON to JSON mapping, I get numeric values for numeric fields (like quantity, item/id) :

      {
      "header": {
      "item": [
      {
      "quantity": 16,
      "unitOfMeasure": "PCE",
      "id": 00010
      }
      ],
      "id": "180220430"
      }
      }

      but when I use the XML to JSON mapping, I get 

      {
      "header": {
      "item": [
      {
      "quantity": "16",
      "unitOfMeasure": "PCE",
      "id": "00010"
      }
      ],
      "id": "180220430"
      }
      }

      I would expect the same result in this case, following the JSON scheme that was uploaded

       

      Kind regards,

       

      Jan

       

       

       

       

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi Jan,

      Thanks for the comment, yes, we know this issue and is getting fixed.  Once fix is available, we will update our release notes.

       

      Thanks

      Deepak

      Author's profile photo Charles Golfman
      Charles Golfman

      Great feature! Deepak G Deshpande

      Is this feature available in the trial account? I am able to import the open api specification but not able to use it in the message mapping.

      Thanks!

      C.

       

      Author's profile photo Bhanu Nanduri
      Bhanu Nanduri

      Hello ,

       

      I have used the Open API specification as my target structure and when i what to duplicate a  node (subtree) the option is greyed out. The attribute is defined as an array and OAS is a valid OAS .

       

      Can you please let me know if there is a limitation.

       

       

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi,

      I see you have created a support ticket, further updates will be shared in the ticket.

       

      Thanks

      Deepak

      Author's profile photo Michael Christa
      Michael Christa

      Hi Deepak G Deshpande ,

      I'm struggeling with the same issue as well. Is there any solution or workaround on this?

      Best regards
      Michael

      Author's profile photo felix stanzel
      felix stanzel

      Hi,

      I am facing the same issue. Where you able to find a solution?

       

      Thanks,
      Felix

      Author's profile photo Michael Christa
      Michael Christa

      Hi Felix,

      unfortunately, I didn't. I did implement a workaround using a groovy script. Thus, I map data beforehand via groovy script to an exchange property. Afterwards I map all the common fields via message mapping. In the end, I append the exchange property to message body.

      Not nice but it works.

      Would be good to know the outcome of that mentioned support ticket.

      Best regards
      Michael

      Author's profile photo venkat maguluri
      venkat maguluri

      HI Deepak,

      I have tried to upload the swagger file in message mapping in CPI but getting below error,

      Error while uploading swigger file in message mapping

       

      could you please help me to fix this issue.

      Thanks in advance.

      Regards,

      Venkat

       

      Author's profile photo Deepak G Deshpande
      Deepak G Deshpande
      Blog Post Author

      Hi Venkat,

      I request you to raise a ticket with all required details on this issue. One of the team member will look into it and provide solution.

       

      Thanks

      Deepak