Skip to Content
Technical Articles
Author's profile photo Archana Shukla

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.

 

<<<< STANDALONE APP-ROUTER BASED FIORI APPLICATION >>>>>>>>>>>>>>

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": "com.sap.bpm.workflow",
    "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 sap.app –> id. Application ID is the ID without dot.

For Example: In below example the sap.app –> 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
/<applicationID>/bpmworkflowruntime/v1/xsrf-token

For Example:
/sapdemobpmstartworkflow/bpmworkflowruntime/v1/xsrf-token
  • 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)
/<applicationID>/bpmworkflowruntime/v1/workflow-instances


For Example:
/sapdemobpmstartworkflow/bpmworkflowruntime/v1/workflow-instances

 

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:
    https://mytrial-dev-workflow-start-sample-approuter.cfapps.us10.hana.ondemand.com/sapdemobpmstartworkflow/index.html

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.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

 

<<<< SAP MANAGED APP-ROUTER BASED FIORI APPLICATION >>>>>>>>>>>>>>

 

I assume the following:

  1.   you have an account in SAP Business Technology Platform.
    • 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, based on standard SAP Managed based app-router which will have input fields and a button to start the workflow (learn more how to do it from here)
    • While creating the application project, ensure that you select these options:
      • Do you want to add authentication? – Yes
      • Do you want to add a data service? – No
  3. You have a Workflow Service Instance based destination created. 
  4.   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)

 

Step 1 : Update mta.yaml

Locate the destination module with the destination-content suffix and Change the scope of the destination by replacing “instance:” with “subaccount

 

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 of the following:

    • you add this route before the generic routes.
    • “authenticationMethod” is “route” (check line 3 in screenshot)
{
    "source": "^/bpmworkflowruntime/(.*)$",
    "target": "/$1",
    "service": "com.sap.bpm.workflow",
    "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, service name and application version 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

You can use this code to get the module path:

var appId = this.getOwnerComponent().getManifestEntry("/sap.app/id");
var appPath = appId.replaceAll(".", "/");
var appModulePath = jQuery.sap.getModulePath(appPath);

 

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

 

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:

 

 

 

Assigned tags

      35 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Taranamjit Kaur Dhindsa
      Taranamjit Kaur Dhindsa

      Nice . Thanks for sharing

      Author's profile photo Vijayalaxmi Bishwal
      Vijayalaxmi Bishwal

      Hello Archana,

      Its nice blog. But I have few doubts.

      You have mentioned to have xs-security.json but as per below link "https://help.sap.com/viewer/e157c391253b4ecd93647bf232d18a83/Cloud/en-US/6416241449b545469210b590f03bd107.html"

      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?

      Thanks,

      Author's profile photo Archana Shukla
      Archana Shukla
      Blog Post Author

      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,
      Archana

      Author's profile photo Vijayalaxmi Bishwal
      Vijayalaxmi Bishwal

      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.

      Author's profile photo Archana Shukla
      Archana Shukla
      Blog Post Author

      You may find the answer in my new blog: https://blogs.sap.com/2020/09/08/calling-external-api-in-custom-task-ui-of-workflow-in-cloud-foundry/

      Author's profile photo Amin Almarsafy
      Amin Almarsafy

      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.

      Regards,

      Amin

      Author's profile photo Amin Almarsafy
      Amin Almarsafy

      Fixed finally, I just didn't have a workflow service bound to the app router

      Author's profile photo Uma Anbazhagan
      Uma Anbazhagan

      Hi Amin,

      I am facing the same issue. Could you pl. let me know how to bind the workflow service to the app router?

      Thanks

       

      Author's profile photo Uma Anbazhagan
      Uma Anbazhagan

      Was Able to do that in mta.yaml file. Thanks again for the hint.

      Author's profile photo Jimmy Arnold Moreno Nuñez
      Jimmy Arnold Moreno Nuñez

      Hi Archana Shukla.

      It's necesary to specify the definition ID in the workflow instance call because I had an error and with this is working.

      data: JSON.stringify({
      	definitionId: "<my_wf_id>",
      	context: <jsonPayload> 
      }),

      Thank you so much.

      Author's profile photo Archana Shukla
      Archana Shukla
      Blog Post Author

      Yes that would be needed because that's the format for calling create workflow instance API. See the API documentation https://api.sap.com/api/SAP_CP_Workflow_CF/resource

      Author's profile photo Jason Scott
      Jason Scott

      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?

      Author's profile photo Max Schnürle
      Max Schnürle

      HI Archana Shukla

       

      is there any answer about this topic?

      how to initiate a workflow instacen from CAP Service? this was also raised here:

      Starting workflow instance from CAP service - SAP Q&A

       

      Best Regards

      Max

      Author's profile photo Koray Yersel
      Koray Yersel

      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": "com.sap.bpm.workflow",
          "endpoint": "workflow_rest_url",
          "authenticationType": "xsuaa"
      },

      As stated in https://answers.sap.com/comments/13196607/view.html 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 com.sap.bpm.workflow 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,

      Koray

       

       

      Author's profile photo Archana Shukla
      Archana Shukla
      Blog Post Author

      Hello Koray,

      You cannot test API calls using Run Configurations. You have to deploy and test.

      Author's profile photo Koray Yersel
      Koray Yersel

      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:
        VCAP_SERVICES={}
      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.

      Regards,

      Koray

      Author's profile photo Archana Shukla
      Archana Shukla
      Blog Post Author

      Awesome, thanks for sharing it for others.

      Author's profile photo Tiago Moises
      Tiago Moises

      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.

      Author's profile photo Punna Rao Vallabhapurapu
      Punna Rao Vallabhapurapu

      Have you got any solution for calling the destination and calling the Odata in Starting application . Please share me if any solution .

      Thanks

      Author's profile photo Ravindra Singh
      Ravindra Singh

      Hi Archana,

      In "SAP MANAGED APP-ROUTER BASED FIORI APPLICATION" scenario is it mandatory to not  have a data service attached to the application as you have mentioned that ensure that you select these options:

      • Do you want to add authentication? – Yes
      • Do you want to add a data service? – No

       

      I have a SAP managed app-router based Fiori application which is using a Odata service. I am trying initiate a workflow following your blog and followed all the steps but getting bad gateway error while fetching xsrf token.

      is any step changed?

       

      Thanks in advance.

       

      Author's profile photo Tejaswi Ayyapusetty
      Tejaswi Ayyapusetty

      Hello Ravindra,

       

      I face 500 Internal Server Error while fetching xsrf-token. Did you find a solution?

       

      Solution: When deployed to Managed Approuter runtime  "xxx-destination-content" module should have dependecy to workflow instance, when standalone app router is used approuter module should have dependecy to workflow instance.

       

      Regards,

      Tejaswi

      Author's profile photo Saranya Sampath
      Saranya Sampath

      Hi Archana,

       

      In cloud foundry, I am migrating  workflow application from neo environment to CF. Created  workflow with custom UI for approving request. But while I am initiating workflow instance, getting below error in service task which was working before in neo environment.

      "The 'Content-Type' header of the HTTP response contained the value 'text/html' not a 'application/json' or a JSON-compatible mime-type as expected"

       

      Thanks

      Saranya

       

       

       

      Author's profile photo Archana Shukla
      Archana Shukla
      Blog Post Author

      Hello Saranya,

      Input payload (or body) to instantiate workflow must be of application/json type. Get more information for how to use CF APIs here [POST: /v1/workflow-instances]

      Author's profile photo Saranya Sampath
      Saranya Sampath

      Hi Archana,

       

      Workflow started successfully. But its not reflecting in MyInbox. If I check Monitor workflow (Workflow Instances) in execution log getting error mentioned in previous post. The error occurred in service task GET request. The service returning response in xml format. and formatting it into json  while calling from service task by adding $format=json.

      Workflow_ServiceTask_Error

      Workflow_ServiceTask_Error

       

      Author's profile photo Archana Shukla
      Archana Shukla
      Blog Post Author

      This is from the service task, you have not used the right header parameters as expected by your service.

      Author's profile photo Jimmy Arnold Moreno Nuñez
      Jimmy Arnold Moreno Nuñez

      Hi Archana Shukla.

      I modified my xs-app.json with your instructions but when I try the option run configurations, I get this error:

      cx

      Maybe I forgot any configuration for bpmworkflowruntime on destination section.

      Thanks in advance.

      Jimmy

      Author's profile photo Archana Shukla
      Archana Shukla
      Blog Post Author

      Is this build time error? From this error it's not clear what is the problem. You can check the entire console to see if there is anything meaningful logged.

      Author's profile photo Jimmy Arnold Moreno Nuñez
      Jimmy Arnold Moreno Nuñez

      This error is when I add this code:

              {
                  "source": "^/bpmworkflowruntime/(.*)$",
                  "target": "/$1",
                  "service": "com.sap.bpm.workflow",
                  "endpoint": "workflow_rest_url",
                  "authenticationType": "xsuaa"
              },  
      Author's profile photo Archana Shukla
      Archana Shukla
      Blog Post Author

      Hello Jimmy,

      The code looks fine. I think you trying to test locally in your SBAS? If yes, then there is already a response from Koray above, you can follow the steps.

      Author's profile photo Punna Rao Vallabhapurapu
      Punna Rao Vallabhapurapu

      Hi Archana Shukla ,

       

      Its Really good . I have taken the sample project and deployed  .its running fine . But Now i want to call the Odata service in my starting application (Capital Expenditure Request Form) . I have updated the  xs-app.json and Manifest.json  but still i am unable to connect the my Odata service . Can you please help me 

      Author's profile photo Archana Shukla
      Archana Shukla
      Blog Post Author

      It is difficult to help you with the limited information. (a) Have you created the destination? (b) Have you added the right destination-based route in your xs-app.json. Send across the screenshots please.

      Author's profile photo Punna Rao Vallabhapurapu
      Punna Rao Vallabhapurapu

      Hi Archana Shukla ,

      Its Really Thanks for your reply .

       

      Author's profile photo mohan dandu
      mohan dandu

      Hi Archana,

      I am trying trigger thw workflow from OnPremise system, could you please help with which URL to choose for creating the instance of the class cl_http_client .

      Author's profile photo Prasad Sistla
      Prasad Sistla

      @mohan dandu

      Were you able to get this information? I am also ,looking for similar scenarios. Thanks.

      Author's profile photo Jency Sekar
      Jency Sekar

      Hi Archana,

      I have followed the steps which you have defined for creating own fiori application in BAS. I have deployed my application but not able to see the UI in workflow fiori launchpad MyInbox application. Could you please help here?

      Thanks,

      Jency S