Skip to Content

Introduction

There are many operations that can be performed on an Integration Flow like create, configure, deploy, etc. using the SAP Cloud Platform Integration’s Web Application. But now with the introduction of remote OData APIs, it is also possible to perform similar operations on the integration flows (also known as Integration Design time artifacts) remotely, using a REST client.

This blog will explain how to Configure and Deploy an Integration design time artifact along with the newly added feature mentioned below.
These API enhancements are further detailed in SAP Help Portal: Integration Content Designtime – OData API.
To try these out on API Business Hub, check out the blog : Cloud Integration: OData API on API Business Hub

New with SAP Cloud Platform Integration 4 August 2018 release:

New feature enhancements include APIs for enabling various operation like Get, Create, Update, Delete and Download of Resources in an Integration Flow.

New with SAP Cloud Platform Integration 7 September 2018 release:

New feature enhancements include APIs for enabling copy of Integration Package from Discover to Design

Configure an Integration Flow

Configure operation allows you get all externalized parameters and also update a single parameter or multiple parameters in a single REST call.

Get Parameter Details

In order to fetch the details of all the parameters externalized in an integration design time artifact, execute the following steps.

  1. The URL for configuring single parameter in one REST call is :

    https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<integrationFlowID>’,Version='<version>’)/Configurations

In the above link,

  • tmnurl represents the URL of the tenant where the integration flow exists
  • integrationFlowID denotes the id of the integration flow
  • version represents the latest active version of the integration flow

NoteintegrationFlowID can be fetched by opening the integration flow in Web UI and checking the ID field, under General tab of the integration flow configuration.

These details must be replaced and updated in the URL.

  1. Paste the above URL in any Rest Client of your choice (e.g. Postman)
  2. Select HTTP GET
  3. Select Send

Single Parameter Update

In order to update a single parameter value of an integration design time artifact, execute the following steps.

  1. The URL for configuring single parameter in one REST call is :

    https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<integrationFlowID>’,Version='<version>’)/$links/Configurations(<parameterKey>)

In the above link,

  • tmnurl represents the URL of the tenant where the integration flow exists
  • integrationFlowID denotes the id of the integration flow
  • version represents the latest active version of the integration flow
  • parameterKey denotes the name of the parameter you wish to update.

These details must be replaced and updated in the URL.

  1. Paste the above URL in any Rest Client of your choice (e.g. Postman)
  2. Select HTTP PUT 
  3. Select Authorizationtab and provide the required authentication TYPE
  4. Select Headers tab and enter x-csrf-token key and its value.

Note : You can do GET operation on http header x-csrf-token : fetch to get the value of x-csrf-token.

  1. In the Body tab, enter the request to update parameter value.

Below is an example of a request body of JSON format to update parameter value

  1. Select Send.

Note: For updating a Scheduler or Timer parameter, the “ParameterValue” should be a valid cron expression and the “DataType” should be “custom:schedule”. Please see the below example.

Multiple Parameter Update

In order to update multiple parameters of an integration design time artifact, execute the following steps.

  1. The URL for configuring multiple parameters using Batch call is :

    https://<tmnurl>/api/v1/$batch

In the above link,

  • tmnurl represents the URL of the tenant where the integration flow exists

These details must be replaced and updated in the URL.

  1. Paste the above URL using any Rest Client of your choice (e.g. Postman)
  2. Select HTTP PUT       
  3. Select Authorizationtab and provide the required authentication TYPE to login to the tenant.
  4. Select Headerstab and enter the following header keys and their value:
    • Set x-csrf-token.
    • Set Content-Type as multipart/mixed; boundary=<batchboundry>. 
  5. Select Body tab and enter the batch request to update multiple parameter values.  
  6. Select Send.

Deploy Integration Flows

It is now possible to deploy an integration design time artifact via remote API call. To check how, execute the following steps.

  1. The URL for deploying is :

    https://<tmnurl>/api/v1/DeployIntegrationDesigntimeArtifact?Id='<integrationFlowID>’&Version='<version>’

In the above link,

  • tmnurl represents the URL of the tenant where the integration flow exists
  • integrationFlowID denotes the id of the integration flow
  • versionrepresents the latest active version of the integration flow
  1. Paste the above URL using any Rest Client of your choice (e.g. Postman)
  2. Select HTTP POST operation
  3. Select Authorization tab and provide the required authentication TYPE to login to the tenant.
  4. Select Headers tab and enter x-csrf-token key and its value.
  5. Select Send.

Resource APIs

The following APIs allow you to manipulate resources in an Integration Flow.

Get All Resources

To fetch all the resources from an integration flow.

  1. Provide the URL with Get Operation

    https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<integrationFlowID>’,Version='<version>’)/Resources

In the above link,

  • tmnurl represents the URL of the tenant where the integration flow exists
  • integrationFlowID denotes the id of the integration flow
  • version represents the latest active version of the integration flow
  1. Update Authorization
  2. Click on Send.

Get Resource

To fetch individual resources from an integration flow.

  1. Provide the URL with Get Operation

    https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<version>’)/Resources(Name='<Resource Name>’,ResourceType='<Type of Resource>’)

In the above link,

  • tmnurl represents the URL of the tenant where the integration flow exists
  • integrationFlowID denotes the id of the integration flow
  • version represents the latest active version of the integration flow
  • Resource Name represents name of the resource with extension.
  • Type of Resource represents the type of the resource
  1. Update Authorization
  2. Click on Send.

Note: In a special case where XSD is referred by a WSDL and use case is read XSD from WSDL folder then user can customer query option.

https://<tmn>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<version>’)/Resources(Name='<Resource Name>’,ResourceType='<Type of Resource’)?ReferencedResourceType=< Type of Resource>

Create Resource

To create a resource in an integration flow.

  1. Provide the URL with POST Operation

    https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<Version>’)/Resources

In the above link,

  • tmnurl represents the URL of the tenant where the integration flow exists
  • integrationFlowID denotes the id of the integration flow
  • version represents the latest active version of the integration flow
  1. Provide CSRF Token (explained in the Integration Flow creation)
  2. Update Basic Authorization
  3. Provide JSON body content, as shown in the example below.
  4. Click on Send.

Note: In a special case where XSD is referred by a WSDL and the use case is to put XSD in WSDL folder, the user can put additional attribute in payload.

Update Resource

To update a resource in an integration flow.

  1. Provide the URL with PUT Operation

    https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<version>’)/$links/Resources(Name='<Resource Name>’,ResourceType='< Type of Resource>’)

In the above link,

  • tmnurl represents the URL of the tenant where the integration flow exists
  • integrationFlowID denotes the id of the integration flow
  • version represents the latest active version of the integration flow
  • Resource Name represents name of the resource with extension
  • Type of Resource represents the type of the resource
  1. Provide CSRF Token (explained in the Integration Flow creation).
  2. Update Basic Authorization.
  3. Provide JSON body content, as shown in the example below.
  4. Click on Send.

Note: In a special case where XSD is referred by a WSDL and the use case is to update XSD in WSDL folder, the user can use a custom query.

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<version>’)/$links/Resources(Name='<Resource Name>’,ResourceType='<Type of Resource>’) ?ReferencedResourceType=< Type of Resource>

Delete Resource

To delete a resource in an integration flow.

  1. Provide the URL with DELETE Operation

    https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<version>’)/$links/Resources(Name='<ResourceName>’,ResourceType='< Type of Resource>’)

In the above link,

  • tmnurl represents the URL of the tenant where the integration flow exists
  • integrationFlowID denotes the id of the integration flow
  • version represents the latest active version of the integration flow
  • Resource Name represents name of the resource with extension
  • Type of Resource represents the type of the resource
  1. Provide CSRF Token (explained in the Integration Flow creation).
  2. Update Basic Authorization.
  3. Click on Send.

Note: In a special case where XSD is referred by a WSDL and the use case is to delete XSD in WSDL folder, the user can use a custom query.

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<version>’)/$links/Resources(Name='<Resource Name>’,ResourceType='<Type of Resource>’) ?ReferencedResourceType=< Type of Resource>

Download Resource

To download a resource in an integration flow.

  1. Provide the following URL with GET operation:

    https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<version>’)/Resources(Name='<Resource Name>’,ResourceType='<Type of Resource>’)/$value

In the above link,

  • tmnurl represents the URL of the tenant where the integration flow exists
  • integrationFlowID denotes the id of the integration flow
  • version represents the latest active version of the integration flow
  • Resource Name represents name of the resource with extension
  • Type of Resource represents the type of the resource
  1. Update Basic Authorization.
  2. Click on Send.

Note: In a special case where XSD is referred by a WSDL and the use case is to download XSD in WSDL folder, the user can use a custom query.

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<version>’)/Resources(Name='<Resource Name>’,ResourceType='<Type of Resource>’)/$value?ReferencedResourceType=< Type of Resource>

Copy Integration Package from Discover to Design

In continuation of OData APIs offerings form SAP Cloud Platform Integration, with version 2.45.x, we have now enabled an OData API to copy an integration package from Discover space to Design space.

  1. The URL pattern of the API is:https://<tmnurl>/api/v1/CopyIntegrationPackage?id='<id>’

In the above link,

  • tmnurl represents the URL of the tenant where the integration flow exists
  • id denotes integration package id. As of now, you can get this id from the URL of your browser’s address field as shown in the below screenshot (encircled)

2. When you perform the POST operation on the mentioned OData API, you shall get an HTTP             201 response code with response content as shown in the below screenshot which signifies               the successful copy of integration flow package from Discover to Design space.

 

Also, below are the other supporting parameters of this OData API

https://<tmnurl>/api/v1/CopyIntegrationPackage?id='<id>’&ImportMode=’<import_mode>’

Values of the import_mode are

  1. OVERWRITE : If you wish to overwrite the existing package which copying, you can provide this value, e.g. https://<tmnurl>/api/v1/CopyIntegrationPackage?id='<id>’&ImportMode=’OVERWRITE’
  2. CREATE_COPY : If you wish to create another copy of the same integration package while    copying and it has to be followed by a suffix, e.g. https://<tmnurl>/api/v1/CopyPackage?id='<id>’&ImportMode=’CREATE_COPY’&Suffix=’123

 

Conclusion

These are the first set of remote OData API’s that are currently available and in the coming months,  we will be releasing more API’s to allow download and delete of an integration flow from the design workspace. Hope this blog helps you in understanding these APIs and gives you enough information to get started with them. Feel free to give us your feedback !

 

To report this post you need to login first.

21 Comments

You must be Logged on to comment or reply to a post.

  1. Harsh Bhatt

    Hi Archita,

    Thanks for sharing! It is really interesting to have this API to do operations on integration artifact. I am trying to list down use cases where this would prove handy. Could you share your insights on where SAP wants to lead us?

    Best regards,

    Harsh

    (0) 
    1. Archita Sarangi Post author

      Hi Harsh,

      The reason why we are investing in API’s is to help oraganizations in their end to end automation and testing needs over a period of time.

      (0) 
  2. Naresh Dasika

    Hello Archita,

    Thanks for sharing the blog. This is really useful.

     

    Couple of questions:

    1. How to get x-csrf-token to “Deploy Integration flow?
    2. When tried to perform GET operation encountered an error as “Invalid key predicate”. PFA screen shot.

    (0) 
    1. Archita Sarangi Post author

      Hi Naresh,

      For fetching the x-csrf-token please do the following steps :

      1. Go the the HTTP “Headers” tab and put the key as x-csrf-token and its value as fetch.
      2. Do a GET call on your URL.
      3. In the response body there might be few errors, which is expected, since GET call on a Deploy URL is not valid.
      4. In the “Headers” tab of the response (beside Body and Cookies) you will get the  x-csrf-token value.
      5. Paste the value in your request Header tab for the x-csrf-token.

      Hope, this is helpful to resolve your issue.

      Best Regards,

      Archita

      (0) 
        1. Archita Sarangi Post author

          Hello Naresh,

          All API’s from SAP are generally published in https://api.sap.com  . In here if you go to API’s and look for Integration API’s you will be able to discover the API’s from CPI. Direct link https://api.sap.com/api/IntegrationContent

          This is periodically updated.

           

          (0) 
  3. Eng Swee Yeoh

    Hi Archita

     

    Thanks for sharing details on this new API.

    I would like to know if we can access artifacts that are still “work in progress”?

    In the example below, I have some changes done, but have not been “saved as a new version” in WebUI. It shows the version as Draft, but when I try to use ‘Draft’ as the version in the GET call, it returns an error.

     

    Regards

    Eng Swee

     

    (0) 
    1. Archita Sarangi Post author

      Hi Eng Swee,

      Yes, we can definitely access the integration artifacts in “DRAFT” state.

      If you are creating a new integration flow and it is in progress, then by default its version is “1.0.0” with the first “SAVE”.

      Even if the integration artifact shows the version as “DRAFT” you can access it via the remote APIs with the latest “active” version. Which, in your case is 1.0.0.

      However, if the integration artifact was previously in a version 1.0.x, and then a user modifies it and just “Saves” it as Draft. You will have to use the version 1.0.x (i.e. the latest active version), in order to access it via Remote API.

      Hope, this clarifies you doubt.

      Best Regards,

      Archita

       

      (0) 
      1. Eng Swee Yeoh

        Hi Archita

         

        Thanks for the quick response. I tried it out again and understand it a bit better now.  Only the latest version is ever available, and if there are any draft changes (not saved into a version yet), they are available via the latest version no.

         

        With the version no as a key field, I was assuming we could access previous versions of the artifact as well. If only the latest version is available, maybe it is better that it is not a required input field? This would save us the need to figure out the version no first before performing the call.

         

        Regards

        Eng Swee

        (0) 
        1. Archita Sarangi Post author

          Hi Eng Swee,

          It is correct that currently only the latest version is allowed to be accessed.

          However, in future when the feature is introduced where we can access the previous versions as well, we would be able to do it using remote APIs without any major changes.

          Hence, it is implemented this way.

          Thanks & Regards,

          Archita

          (0) 
      2. Eng Swee Yeoh

        Hi Archita

         

        I noticed further that query on the main entity set for IntegrationDesigntimeArtifacts (URL = https://<hostname>/api/v1/IntegrationDesigntimeArtifacts ) does not work, and returns the following error.

        {
            "error": {
                "code": "Not Implemented",
                "message": {
                    "lang": "en",
                    "value": "Not implemented"
                }
            }
        }

         

        Typically for OData APIs, if we query the entity set without providing any further key value or query string, it would return a paginated results of all the records for that entity set. As an example, CPI’s other OData API entity, IntegrationRuntimeArtifacts does return such result.

        Having such a result would allow us to remotely access details such as integrationFlowID and version, without having to manually login through WebUI and navigate to the design artifact to find them.

         

        Regards

        Eng Swee

        (0) 
        1. Archita Sarangi Post author

          Hi Eng Swee,

          If you are trying to do a GET call in order to access the details of all the integration designtime artifacts, then it is not implemented yet.

          Currently, you can access the details of only one artifact at a time using the API:  https://<hostname>/api/v1/IntegrationDesigntimeArtifacts(Id='<ArtifactID&gt;’,Version='<version>’)

          However, I will take your feedback and discuss if we can support this in future releases.

          Best Regards,

          Archita

           

          (0) 
          1. Eng Swee Yeoh

            Hi Archita

             

            Thank you for both your responses. Ok, so if there are plans for access to other versions, then having version no as the key would make sense. Would be great if the functionality is extended to support getting all the artifacts, as that is a very common OData feature.

             

            Regards

            Eng Swee

            (0) 
      3. Devin Mens

        Hi Archita,

        Just to piggyback on what Eng Swee is asking, is there anyway to get the latest version of an IFlow from the REST api and if not is that functionality expected at some point?

         

        Thanks,
        Devin

        (0) 
        1. Archita Sarangi Post author

          Hi Devin,

          With the current available features, it is not possible to get the latest version of an already existing integration flow through remote API calls.

          However, I will take this as a feedback and discuss if we can plan this in future releases.

          Thanks & Regards,

          Archita

          (0) 
    1. Archita Sarangi Post author

      Hi Vadim,

      The resource APIs are available 1806 release onward.

      Can you please check if you are trying it in the latest released software?

      Thanks & Regards,

      Archita

      (0) 
  4. Pritham Rao
    Hi Archita,
    
    
    Is there a list of resource types we can post to the iflow. for example:
    "ResourceType":"xslt"
    
    I need to add .xml file to the resources folder of an iflow. But that was giving an error
    
    Would that be possible?
    
    REgards,
    
    Pritham

     

    (0) 
    1. Archita Sarangi Post author

      Hi Pritham,

      We do not support .xml file as of now.

      The list of resources supported currently are

      groovy, gsh, xsl, xslt, jar, edmx, js, mmap, opmap, wsdl, xsd, zip

       

      Regards,

      Archita

      (0) 
  5. Pritham Rao

    Hi Archita,

    I have a requirement to read the Credentials which is of type oauth2:default. I need to read the Client ID and Client secret.

    I am using the API as below

    GET https://tenanturl.com/api/v1/UserCredentials(‘Credentialname’)

     

    In the user field I get the client id which was saved

    <d:User>sb-xxxxxx!t2299</d:User>

    But the Password field where I was expecting the client secret I am getting null. Is there any other way (possibly more secure) in which I can retrieve the client secret stored in the credentials. I need this to use in my iflow to connect to another request reply step.

    Regards,

    Pritham

     

     

     

     

     

    (0) 

Leave a Reply