Migrate your SAP BTP Neo Workflow applications to ...

Venugopal · ‎2023 Sep 14

Introduction

SAP Build Process Automation is the successor product of SAP Workflow Management in SAP Business Technology Platform.It includes Workflow, Business Rules, Process Visibility and Robotic Process Automation capabilities with no-code development experience, better integration across these capabilities and life cycle management.The key benefits of migrating to SAP Build Process Automation are explained in my previous blog. SAP Workflow Management is deprecated from 2022 August 15th and customers need to plan their workflow/business rules investments in BTP to SAP Build Process Automation. SAP has also announced the sunset of legacy Neo environment and 2028 Dec 31st is the planned sunset timeline.Workflow and Business Rules are two services in Neo environment consumed by customers to build various process automation use cases. Even though Neo sunset time line is 2028 Dec 31st, customers using Workflow and Business Rules capability may need to migrate earlier to SAP Build Process Automation due to the deprecation of SAP Workflow Management.

Neo Workflow / Business Rules to SAP Build Process Automation - Value Proposition

SAP Workflow Management has been used by customers in Neo and Cloud Foundry environment but the Cloud Foundry deployment has more capabilities in terms of infrastructure,life cycle and functional scopes.Some of the key capabilities of SAP Build Process Automation compared to Neo environment is given below and this helps to understand the value proposition to migrate existing Neo based Workflow solutions to Cloud Foundry.

Workflow/Business Rules - Neo Environment	SAP Build Process Automation
Pro-Code tooling using WebIDE.	Pro-Code tooling using SAP Business Application Studio. No-Code tooling enable Citizen developers to model and deploy process applications.
Deploy solutions in SAP Managed Neo Data Centers	Deploy solutions in Cloud Foundry environment based on hyper scalers data centers.
Limited capabilities.	Process Visibility, Robotic Process Automation and many more capabilities.
Loosely coupled integration between Workflow and Business Rules.	Out of the box integration across all capabilities in SAP Build Process Automation and also with other services like SAP Build Work Zone , SAP Document Management.
No content store.	Content store provides out of the box process and automation content.
Multiple deployment of artifacts part of a solution.	Single deployment of all artifacts. Versioning all artifacts in a project.
No SAP Task Center integration.	Out of the box integration with SAP Task Center.
SAP Portal Service to consume process and related applications.	SAP Build Work Zone Standard or Advanced version. SAP Build Work Zone standard usage is included in SAP Build Process Automation.
Single metric - active users.	Multiple metrics for different usage types.

Migration of Neo Workflow Projects to SAP Build Process Automation

A Neo workflow projects consists of Workflows,start and task user interfaces developed in SAP UI5. In Neo environment, workflow models and SAP UI5 applications are not deployed together even though these artifacts might be part of the same WebIDE projects. As a first step of migration these artifacts needs to be part of a multi target application using SAP Business Application Studio. There is no out of the box migration but it is possible to copy and paste the content to a Multi Target application and make the necessary modifications to deploy the content to SAP Build Process Automation. The migration steps are also described in the official SAP documentation.
The migration does not require any application logic changes in Workflow or SAP UI5 application. All the modeled content can be reused. The Workflow models require re assigning of the Task UIs in User Tasks.Service tasks may need modifications depending on the changes in the respective urls,destinations and authentication. SAP UI5 applications need to adapt the API calls using a service route or destination.
All the existing runtime workflow instances, task instances,logs and context data in the neo environment cannot be migrated to SAP Build Process Automation. All ready or reserved user tasks need to be completed by the approvers using MyInbox in Neo environment. When all workflow instances are successfully completed, the runtime data can be retrieved using the Data Export API.

Workflow APIs in Neo and SAP Build Process Automation

There are no big changes between Workflow APIs in Neo and SAP Build Process Automation APIs. Apart from the host name change, there is no change in the path. Most of the Neo Workflow APIs are included in SAP Build Process Automation except Workflow Definitions APIs and other life cycle apis.
Neo Workflow APIs supports Basic and OAuth 2.0 based authentication , but SAP Build Process Automation supports only OAuth 2.0 based authentication. It is possible to have technical user based authentication using service instance credentials.

Prerequisites

A subaccount in one of the Cloud Foundry data center with SAP Build Process Automation available.

SAP Build Process Automation Subscription and configuration.There are multiple SAP Build Process Automation plans. Depending on the available plans subscribe and configure SAP Build Process Automation in a Cloud Foundry data center.There are four key service plans mandatory for the current Workflow and Business Rules use cases. standard-user, advanced-user,api-calls and storage.

SAP Build WorkZone Standard.Subscribe and configure SAP Build Work Zone standard.

SAP Business Application Studio subscription. Create a space with Workflow and Fiori plugins are enabled.

Create Multitarget Application.

Import your WebIDE Neo Workflow Project to SAP Business Application Studio.

Create a new Basic Multitarget Application(MTA) project in SAP Business Application Studio.

New Multitarget Application

Migrate Workflows

Right click on the mta.yaml file and add a workflow module to the newly created Multitarget application. This includes the Workflow definition name. This will add a new workflow module(default name workflow-module) and update the mta.yaml file with appropriate configurations.

The generated Workflow module will add the required folder structure in the project. The mta.yaml file will have a new module with name workflow-module and a resource sap_processautomation with parameters service as process-automation-service and plan as standard.

Delete all folders newly created in the Multitarget Application under the folder workflow-module.

Copy all Neo Workflow Project folders workflows,scripts,sample-data and webcontent, paste to workflow-module folder in the Multitarget Application project.

Make sure the destinations configured in service tasks have valid authentication mode. for eg: Workflow or Business Rules POST APIs in Neo supports Basic authentication with X-CSRF token path. In Cloud Foundry Workflow or Business Rules support only OAuth based authentication and no X-CSRF token path is required.

Open the workflows and make sure all your script tasks,email tasks are configured the same way as in Neo project. The user tasks will show an error marker due to missing SAP UI5 application assignment.

Migrate SAP UI5 components used as Workflow Task UI

If workflows and workflow start or task UIs are in a different projects, create a new Multitarget Application Project as described in the Create Multitarget Application step and continue.

Add Approuter Configuration

Right click on mta.yaml file in the Multitarget Application project. Add an approuter configuration to integrate SAP Build Work Zone standard with Workflow start and task UI application. This is required only if the Multitarget Application Project contains SAP UI5 components.

Enter an business solution name which will be used later in the Workflow User Task configuration.

The mta.yaml file now contains the required configurations to consume a SAP UI5 component using the managed approuter from SAP Build Work Zone standard.

Copy Application ID from Neo SAPUI5 Project

Open the manifest.json file of the SAPUI5 component in the Neo Project. Copy the value of id property under sap.app.It consists of the name space and SAP UI5 component name. The last segment of the value is the component name and the rest is name space. In the below example onbequip is the component name and com.sap.cloud.workflow.samples is the name space. These two values are required in the next steps.

Add a SAPUI5 component as Workflow Task UI

Right click on mta.yaml file and add a SAPUI5 component (Workflow UI) as Task UI to the Multitarget Application Project.

Enter the module name copied from the Neo manifest.json file. The last segment of the copied id property under sap.app.

Select the UI Type as Task UI.The same approach while creating a Workflow Start UI.

Enter the same application namespace and a view name.Copy the same view name from the Neo Project.Application namespace is the id property value under sap.app except the last segment.

The mta.yaml file will be updated with the HTML5 module and resources.The generated code contains many helper functions in component.js ,service route definition in xs-app.json file which simplify the migration of SAP UI5 component and consuming SAP Build Process Automation APIs.The manifest.json contains the business solution name under sap.cloud

The generated SAP UI5 component has folders under webapp such as controller,css,i18N,model,tet,utils and view. The Component.js , index,html and manifest.json files are directly under the webapp folder.There will be equivalent folders and files in the Neo project.

Enhance the Neo project Component.js or controller.js files or any helper files with api or model access using the generated java scripts explained below.

After modification copy and paste the content of webapp folder from Neo project to new Multitarget Application project.

Using SAP Build Process Automation APIs from SAP UI5 applications

SAP Business Application Studio provides SAPUI5 based start and task UI generators simplify the Workflow UI development. The generated code contains Workflow API access including access to Workflow context and event handlers to complete the task.A service route or destination is defined in the xs-app.json file of a SAPUI5 component.The Workflow specific changes generated in the SAPUI5 component are given below.

Access to SAP Build Process Automation service instance route is generated in the xs-app.json file. If there are other service instance or destinations used in a SAP UI5 component, define the respective routes as service endpoint or destination. Please go through Neo to Cloud foundry application descriptor mapping.

 {

      "source": "^/bpmworkflowruntime/(.*)$",

      "target": "/public/workflow/rest/$1",

      "service": "com.sap.spa.processautomation",

      "endpoint": "api",

      "authenticationType": "xsuaa"

 },

2. Access to workflow context in component.js file. The below code snippet provides access to workflow context and bind to a model. The helper functions formulates the API endpoint and call the task context API. These functions can be copied and adapted in the Neo based SAP UI5 component or controllers where Neo Workflow APIs are used.

          setTaskModels: function () {

          // set the task model

          var startupParameters = this.getComponentData().startupParameters;

          this.setModel(startupParameters.taskModel, "task");



          // set the task context model

          var taskContextModel = new sap.ui.model.json.JSONModel(

            this._getTaskInstancesBaseURL() + "/context"

          );

          this.setModel(taskContextModel, "context");

        },



        _getTaskInstancesBaseURL: function () {

          return (

            this._getWorkflowRuntimeBaseURL() +

            "/task-instances/" +

            this.getTaskInstanceID()

          );

        },



        _getWorkflowRuntimeBaseURL: function () {

          var appId = this.getManifestEntry("/sap.app/id");

          var appPath = appId.replaceAll(".", "/");

          var appModulePath = jQuery.sap.getModulePath(appPath);



          return appModulePath + "/bpmworkflowruntime/v1";

        },



        getTaskInstanceID: function () {

          return this.getModel("task").getData().InstanceID;

        },

3. Adding action buttons and Event handlers to complete the task.

            this.getInboxAPI().addAction(

            {

              action: "APPROVE",

              label: "Approve",

              type: "accept", // (Optional property) Define for positive appearance

            },

            function () {

              this.completeTask(true);

            },

            this

          );



          this.getInboxAPI().addAction(

           {

              action: "REJECT",

              label: "Reject",

              type: "reject", // (Optional property) Define for negative appearance

            },

            function () {

              this.completeTask(false);

            },

            this

          );

        },

4. Completing Task and call Task Instance Patch API. The helper function _patchTaskInstance can be modified with appropriate response data as context.

        completeTask: function (approvalStatus) {

          this.getModel("context").setProperty("/approved", approvalStatus);

          this._patchTaskInstance();

          this._refreshTaskList();

        },



        _patchTaskInstance: function () {

          var data = {

            status: "COMPLETED",

            context: this.getModel("context").getData(),

          };



          jQuery.ajax({

            url: this._getTaskInstancesBaseURL(),

            method: "PATCH",

            contentType: "application/json",

            async: false,

            data: JSON.stringify(data),

            headers: {

              "X-CSRF-Token": this._fetchToken(),

            },

          });

        },



        _fetchToken: function () {

          var fetchedToken;



          jQuery.ajax({

            url: this._getWorkflowRuntimeBaseURL() + "/xsrf-token",

            method: "GET",

            async: false,

            headers: {

              "X-CSRF-Token": "Fetch",

            },

            success(result, xhr, data) {

              fetchedToken = data.getResponseHeader("X-CSRF-Token");

            },

          });

          return fetchedToken;

        },



        _refreshTaskList: function () {

          this.getInboxAPI().updateTask("NA", this.getTaskInstanceID());

        },

Update User Task with User Interface

The updated SAP UI5 components need to be assigned as Task UIs in the new Multitarget Application Project. Open the Workflow model and select User task and assign the SAP UI5 component.The new Business Solution Name and HTML5 app name will be updated.The SAPUI5 component will be the same as in Neo project.

Migrate SAP UI5 components used as Workflow Start UI

Migration of a Task UI component Start UI component are very similar except the following.

While adding a Start UI component, choose UI Type as Start UI.

The Event handler implementation to start a workflow instance implemented in Controller.js needs to enhance while calling Workflow start POST API

The below code generated in a Workflow Start UI Controller.js to start a workflow instance can be reused while enhancing the SAP UI5 component from Neo WebIDE project.

startWorkflowInstance: function () {

          var model = this.getView().getModel();

          var definitionId = "SimpleWorkflow";

          var initialContext = model.getProperty("/initialContext");



          var data = {

            definitionId: definitionId,

            context: JSON.parse(initialContext),

          };



          $.ajax({

            url: this._getWorkflowRuntimeBaseURL() + "/workflow-instances",

            method: "POST",

            async: false,

            contentType: "application/json",

            headers: {

              "X-CSRF-Token": this._fetchToken(),

            },

            data: JSON.stringify(data),

            success: function (result, xhr, data) {

              model.setProperty(

                "/apiResponse",

                JSON.stringify(result, null, 4)

              );

            },

            error: function (request, status, error) {

              var response = JSON.parse(request.responseText);

              model.setProperty(

                "/apiResponse",

                JSON.stringify(response, null, 4)

              );

            },

          });

        },



        _fetchToken: function () {

          var fetchedToken;



          jQuery.ajax({

            url: this._getWorkflowRuntimeBaseURL() + "/xsrf-token",

            method: "GET",

            async: false,

            headers: {

              "X-CSRF-Token": "Fetch",

            },

            success(result, xhr, data) {

              fetchedToken = data.getResponseHeader("X-CSRF-Token");

            },

          });

          return fetchedToken;

        },



        _getWorkflowRuntimeBaseURL: function () {

          var appId = this.getOwnerComponent().getManifestEntry("/sap.app/id");

          var appPath = appId.replaceAll(".", "/");

          var appModulePath = jQuery.sap.getModulePath(appPath);



          return appModulePath + "/bpmworkflowruntime/v1";

        },

      }

Build and deploy the Multitarget Application

After migrating the Workflows and SAP UI5 components, build the project. A Successful build will create a .mtar archive under mta_archives folder in the project. Deploy the archive using the context menu. A successful deployment list the deployed workflows in Manage Process application in SAP Build Process Automation and SAP UI5 modules under HTML5 Applications in BTP Cockpit.

If there are errors during deployment possible solutions are available in the SAP Business Application Studio troubleshooting page under deployment or HTML5 Applications.

Known Limitations

Workflow definition specific APIs are not supported.

Embedding Monitor Workflow applications in SAP Build Work Zone not supported.

Migrate Business Rules Projects to SAP Build Process Automation

SAP Business Rules service in Neo environment can be migrated to SAP Build Process Automation by exporting from Neo and import the same project in SAP Build Process Automation using Manage Rules Project application. Manage Rules Project application supports only reusing existing Business Rules projects from Workflow Management and not creating net new Business Rules Project. New Business Rules Projects can be modeled using the Decision capability.

Business Rules APIs in Neo and SAP Build Process Automation

SAP Build Process Automation provides only runtime APIs to execute rules. The client applications consuming Business Rules can use the runtime API and execute the rules.The credentials can be used from a service instance of SAP Build Process Automation.
The following runtime is a Decision runtime url example based on SAP Build Process Automation tenant in US10 data center.

https://spa-api-gateway-bpi-us-prod.cfapps.us10.hana.ondemand.com/public/rule/runtime/rest/v2/rule-serivces

Known Limitations

Business Rule Repository APIs are not available in SAP Build Process Automation.

Embedding Decision controls in external applications are not supported.

Integration with SAP systems supported only using Manage Rule Projects application.

Migration of related services used in Workflow Management solutions

There will be other BTP services from Neo environment used in a Workflow Management solution like Integration, Document Management, Mobile ,HANA etc. There are migration guidelines for these services available and please follow the documentation.