Skip to Content
Technical Articles

Starting Workflow from Custom Fiori Application in Cloud Foundry

I often see developers’ having difficulty in coding their SAPUI5 application to start SAP Cloud Platform Workflow from their custom application. In one of my previous blog I have explained how to achieve this in Neo environment but with cloud foundry there are few significant differences which need to be understood to ensure that you successfully achieve starting the workflow in CF as well.

Disclaimer: I do not intent to explain about cloud foundry concepts in this blog and how to create SAPUI5 application in CF.

I assume the following:

  1.   you have an account in SAP Cloud Platform Cloud Foundry environment.
    • you have enabled Business Application Studio subscription
    • you have Developer role assigned to your user to access application studio
  2.   you have created a Fiori application in studio which will have input fields and a button to start the workflow (learn more how to do it from here)
  3.   you have Workflow entitlement (learn more about setup from here)
    • you have created workflow service instance in your cloud account with minimum scope of WORKFLOW_INSTANCE_START
    • you have WorkflowDeveloper, WorkflowInitiator and WorkflowAdmin roles assigned to your user which will be used to access the workflow editor in app-studio, start the workflow using APIs and access the Monitor Workflow apps respectively.
    • You have already created and deployed a workflow in your account. (learn more from our blog or from the help portal)
    • you know how to work with Workflow API (here is the link)

So, let us now see what all changes are needed in your MTA project to start workflow.

Step 1 : Basic Checks

  1. First check if you have xs-security.json file in your app-router based MTA project. This will be used to authenticate your application via xsuaa while calling Workflow APIs. Usually while creating the Fiori Module from Business Application Studio, you should choose to add authentication to the Fiori Module which will automatically create this xs-security.json file and associate this xsuaa resource to app-router.


    • If you have not done that, then you can manually add this file in your MTA project with the given content and update the resources and app-router module section of the mta.yaml file as shown.


  1. If you have workflow module created in different MTA project than the custom application, then you also need to add the workflow service instance resource in mta.yaml file (see line 45 in screenshot below) and then add the dependency of the workflow instance to app-router in module section (see line 17 in the screenshot below)

Step 2 : Update xs-app.json of Fiori Module

Next update the route in your Fiori Module application. For that, open xs-app.json file of your fiori module and add this route. Make sure you add this route before the generic routes.

    • Also ensure that the “authenticationMethod” is “route” (check line 3 in screenshot)
    "source": "^/bpmworkflowruntime/(.*)$",
    "target": "/$1",
    "service": "",
    "endpoint": "workflow_rest_url",
    "authenticationType": "xsuaa"


Step 3: Update Controller.js of Fiori Module to call Workflow APIs


Update Controller.js file to call workflow start APIs. Before calling the workflow instance APIs to start the workflow, you need to first get the xsrf-token and then call the API.

  • To do so, you will also need information of the application ID that will be prefixed with API host URL. This is needed because your custom application will be routed via the app-router application. You can get this information from the manifest.json file inside your fiori module as –> id. Application ID is the ID without dot.

For Example: In below example the –> id is sap.demo.bpm.startworkflow so the application ID becomes sapdemobpmstartworkflow

  • Now you need to update the code in Controller.js to first make a GET API call for XSRF token

For Example:
  • Next, you will use this xsrf-token to make the POST API call to instantiate workflow. You will need to pass the body which contains the information of workflow definition Id and the initial context. (know more about the APIs from here)

For Example:


These are the 3 simple steps you need to do in your application to start workflow from any of your custom application.

Quick summary of all the steps:

  1. Create MTA Project.
  2. Create Workflow Module in your project and design your workflow.
  3. Create Fiori Module with standalone app-router and add authentication.
  4. Update the xs-app.json of the Fiori Module to add the bpmworkflowruntime route.
  5. Design your Fiori application with the needed input fields and a start button.
  6. Update the Controller.js of your Fiori application to code the start button by calling the workflow APIs to first get xsrf-token and then instantiate the workflow.
    • Don’t forget to prefix the API URL with application ID.
  7. Build and deploy the application.
  8. Finally access the application from cloud cockpit. Click to start the application and prefix the index.html with application ID. For Example:

I have also created a sample project that will help you identify the needed changes in your custom application to start the workflow.

  • Download the project.
  • extract the zip and import the tar file in your business application studio.
  • open mta.yaml file and adjust the workflow instance name and the plan based on the cloud tenant you are going to deploy the application (line numbers 9 and 45 to 49 in sample application),
  • build & deploy the application.


This is the first blog of the series where I intend to provide answers to all your queries on using custom application with workflow in cloud foundry. In upcoming blogs, I will guide you:




You must be Logged on to comment or reply to a post.
  • Hello Archana,

    Its nice blog. But I have few doubts.

    You have mentioned to have xs-security.json but as per below link “”

    we need to delete app router and xs-security.json. So if we are deleting these files then also I am able to create my inbox items and i can complete through API calls.

    My query :

    1. What is the difference of having or deleting approuter/security.json file ?
    2. How to call any other http service?
    3. where to add destination for routing to external http service?


    • Hello Vijaylakmi,

      • The link you pointed is for Custom Task UI and this blog is about starting workflow from standalone custom application. In former, the xsuaa of the workflow service instance is used to make the service call from the task UI which is part of workflow module, but in latter there is no xsuaa specified in the app-router and therefore you need the xs-security json. note that the custom application is routed via routes of app-router.
      • For next two, I will soon publish a blog on how to consume external APIs. Just to answer your query shortly, you need to create a destination in your sub-account, then update xs-app.json to call the destination based route, and then make make an ajax call from your application.

      Hope that helps,

  • Thanks Archana for clarification.

    I have created destination and when I add the same in xs-app.json, its not loading component.js file. And without that destination it loads my UI but the ajax call goes to 404 not found error.

    Please provide some light on this. To point again I have custom UI foir which I have removed xs-security.jason and approuter.

    Many thanks for your response.

  • Hi Archana,

    Thank you for the blog. I have used your previous blog on the same subject for neo before and it was very helpful.

    Now that I am using CF, this one is not working for me, not sure where I am going wrong.

    I have already created a workflow instance and successfully tested it in the API hub to create a new workflow instance. which I can confirm has been created and can see the user task in my inbox (which I deployed using the workflowtiles sample app using webide).

    I have already successfully migrated my app from neo to CF into a mta project using webide.

    the mta has an app router, flp module and a ui5 module which contains the app.

    I tested the app and it is working fine. now I want to add a button to start the workflow instance.

    I confirmed xs-security.json already had the code in this blog as well as the uaa service in the mta.yaml being in the require section of the app router and in the resource section.

    As soon as I added the bpmworkflowruntime route to the xs-app.json the app no longer starts I get a failed to load ui5 component error.

    I replaced workflow_rest_url with the workflow_rest_url from the workflow instance service key. but I am still getting the same error. I also can confirm that the authenticationMethod in the xs-app.json is route. as soon as I remove the route and redeploy the app it works fine.

    can you advise on what could be the problem?

    Thank you.



  • Hi Archana Shukla , If your app backend was a CAP service would it be better to start workflows from there instead of from the fiori app frontend? I’m wondering what the pros and cons would be. I know elsewhere in some answers there is a recommendation to start workflow using CPI for example if the initiator is an enterprise messaging message.

    So I’m wondering for a CAP project should we be starting workflows from CAP?

  • Hi Archana,

    using your blogs I could create a workflow project template including workflow start UI, task UI and OData calls through task UIs and workflow service tasks. Now I am testing the preview / run configurations capabilities of BAS. I am having trouble with the bpmworkflowruntime route below:

        "source": "^/bpmworkflowruntime/(.*)$",
        "target": "/$1",
        "service": "",
        "endpoint": "workflow_rest_url",
        "authenticationType": "xsuaa"

    As stated in I have to remove the route from xs-app.json to be able to start my “workflow start UI” in BAS runtime. Or else I am getting following error: (A route requires access to service but the service is not bound) I think if I can reference this route using a proper destination I won’t have this problem. Is there a possibility to this?

    Thanks and regards,




      • Hi Archana,

        Actually Yuval Morad showed me how to do it:

        1. Create run configuration as intended. Bind destinations and xsuaa if needed.
        2. SAP BAS > Cloud Foundry Targets > Find your worklow service instance. Right click “CF: bind a service to a locally run application” > Bind it to your ui module
        3. Open the created .env file and ‘cut’ the workflow object from VCAP_SERVICES. Take it basicly in your clipboard. After the cut .env file should look like this:
        4. Paste the content in .env1 (basicly to your run configuration env file) VCAP_SERVICES right after xsuaa (if you have it of course). You have make sure that the content is a valid json.
        5. With this manual addition in your .env1 file you can also call workflow APIs in the preview mode.



  • Hi!
    I took the example project in the tutorial and successfully deployed it.
    Now, I need to consume a destination to get information before starting a workflow
    In this example project structure CF, how do I declare the destination to be used in the initial form?


    Thanks in advance.