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.

 

<<<< 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:

 

 

 

27 Comments
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 "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,

    • 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

  • 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.

    Regards,

    Amin

    • 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

      /
  • 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": "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

     

     

      • 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

  • 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.

  • 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.

     

    /
  • 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

     

     

     

    • 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]

  • 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

     

    /
    Workflow_ServiceTask_Error
  • /
    cx
    • 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.

      • This error is when I add this code:

                {
                    "source": "^/bpmworkflowruntime/(.*)$",
                    "target": "/$1",
                    "service": "com.sap.bpm.workflow",
                    "endpoint": "workflow_rest_url",
                    "authenticationType": "xsuaa"
                },  
        • 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.