Skip to content
This repository has been archived by the owner on Jan 4, 2024. It is now read-only.

Latest commit

 

History

History
210 lines (126 loc) · 9.63 KB

HOW-TO.md

File metadata and controls

210 lines (126 loc) · 9.63 KB
Raw

How To Guide for Workflow Template Application

Chris Jobson 16th June 2021

Table of Contents

Initial Configuration

How to Build and Deploy the Application and Workflow

How to Determine the Basic Structure

How to Modify the workflow with no difference to the sync points

How to Modify the application UI with no difference to the sync points

How to Add new sync points

Initial Configuration

The application contains some configuration options that are relevant to the sample use case. These are defined in the file manifest.json under the card/src folder. For further details of the structure of the manifest file and the configuration parameters, read the Overview document.

These configurations are done in 2 places:

  • My the system admin who coinfigures the destinations and company wide property defaults.
  • My the workspace owner who can adjust workspace-specific values for the peorpties (but cannot adjust the destinations)

The following properties are relevant to running this sample:

  1. approver - this defines the user ID of the user who will receive approval tasks generated by the workflow. Set this to the user ID returned by the IDP for this user. The user referred to here will then receive workflow tasks related tot he approval requests.

  2. workflowDefinitionId - this is the name of the workflow definition used to handle the workflow itself. This should match the workflow that is deployed into the workflow engine. You can keep this the same as the default value supplied here, sap.wz.journey.template.workflow.

  3. documentProvider - this determines what document provider to use for the sample. It can either be the values JAM or CMIS, depending on whether you want to save documents in JAM or a CMIS-compliant document storage system. If it is set to JAM, then you must create a destination to JAM in Cloud Foundry that matches the destination named in the destination configuration myJAMDestination. Similarly, if set to CMIS you must ensure a suitable Cloud Foundry destination exists that points at your CMIS provider that matches the destination named in myCMISDestination.

  4. userId / userName / userEmail - these are automatically obtained from Workzone, but can be replaced by alternative versions if required

In addition to configuratin properties, destinations are also configurable.

  1. myJAMDestination - as mentioned above, this refers to a Cloud Foundry destination that points at JAM (if required for document storage).

  2. myCMISDestination - again, as mentioned above, this refers to a Cloud Foundry destination that points at your CMIS provider (if required for document storage).

  3. myWorkflowDestination - this is required by the application to call workflow APIs. The referenced destination (default Workflow_API) should exist and point to the workflow engine. Please see this document for help in setting up this destination: How to configure a Workflow endpoint in Cloud Foundry

How to Build and Deploy the Application and Workflow

There are two approaches to building and deploying the application and workflow:

  1. Create a single deployable package

  2. Create separate workflow and application packages

Create a single deployable package

You can create a single package, and then use the Workzone Package Deploy capabilities to deploy the application and workflow as a single unit. Once deployed, the package can then be installed and made available for consumption in target workspaces.

The package creatino step requires the installation of certain package building tools. To do this, you must first install the necessary npm packages at the root of the directory tree:

npm i

After this, you can use the command npm run build-all to build the necessary components. This will perform a variety of steps, and the end result should be a file called package.zip which can then be uploaded as a content package into SAP Work Zone.

Create separate workflow and application packages

Alternatively, the application and workflow can be build indepenently of each other and installed separately. To achieve this, you will need to install certain NPM packages:

  1. @ui5/cli
  2. @sap/ui5-builder-webide-extension
  3. mbt

Either install these globally or locally, as appropriate.

To create the workflow, first create an MTAR:

cd workflow
mbt build -s .

Then deploy the MATR:

cf deploy <path to MTAR>

This should deploy the workflow and it should be visible via the workflow definition monitor application in Workzone.

To create the application, first build the distribution:

cd card
ui5 build

This will create a new folder dist. Then zip the distribution folder:

zip -r application.zip dist

The final zip file can then be uploaded in workzone via the UI Ibtegration card uploader.

How to Determine the Basic Structure

When creating an aplication and workflow pairing, these are the main things to consider:

  1. The workflow will use a number of intermediate message event points to synchronise

    When the UI application queries the workflow, it should return a context object that indicates what the current intermediate message event point is. This allows the UI to sync itself to that point. If the workflow is performing some long running operation or operations, then it might not be at an intermediate message event point; in which ase, the UI application will poll it until it does.

    Split the workflow into groups of actions, separated by intermediate message event points. Each intermediate event point is used to propvide new context to the workflow.

  2. Typically, the UI application will either send a message to the workflow (calling _advanceWorkflow) - in which case the workflow moves to the next intermediate message event point - or the UI application just saves the latest version of the context object against the workflow (calling _updateWorkflow).

    When the workflow is at an intermediate evenet point, the app status handler for this point is called, allowing the code to set any state that is appropriate.

  3. When a wizard step is completed, a cleanup event handler will be called that allows the application to cleanup or or set any state that is required.

How to Modify the workflow with no difference to the sync points

The underlying workflow can be adjusted easily if there are no changes to the sync points. In this case, simply add extra steps in the workflow. For example, if we look at the example workflow, we see this:

This sequence of steps simply adds a 'delay' to the workflow to simulate what might happen if we were to initiate an interaction with an external system. Obviously, in an actual customer landscape this would be changed to a more realistic scenario. For example, assume we want to create an incident in Service Now, we could simply replace the above 'Simulate SNOW' step with an actual external API call to the SNOW systems:

Alternatively, you could easily just add extra workflow steps in here -- including tasks for approval for example -- with no impact on the UI at all.

The main thing to note is that when adding additional workflow steps, provided the Intermediate Message event points are untouched, you can add as many extra steps as you want.

How to Modify the application UI with no difference to the sync points

Leaving the sync points alone means that the application and workflow can be independently modified but still work together. Effectively the application and workflow fit together and will continue to work.

In this case, simply add more UI steps, and after each UI step is complete simply update the context object (no need to advance the workflow unless required).

For example, let's add a new sub-step that simply captures additional information. To do this, perform the following steps:

  1. Decide on a name for the sub-step (this will then be used as a property in the context object to place additional properties that are captured in the sub-step)

  2. Create an initialization definition for the property in the configuration init file.

  3. Add a new fragment corresponding to the sub-step

  4. Reference this fragment in the wizard step

  5. Add to the controller any event handers triggered by button's etc. added to the sub-step.

  6. If necessary, adjust any workflow scripts or service tasks/user tasks to reference the context object properties affected by this sub-step.

The new sub-step would be implemented via a fragment that then defines the UI that binds to the new sub-step property. To make this concrete, let's modify the existing template application by adding a sub-step in main step 2 to capture the employee's doctor/physician details.

  1. Let's call the sub-step 'doctorDetails'

  2. Let's define this in the init for the context object:

  3. Let's create a new fragment 'step2_5_doctorDetails.fragment.xml'

  4. Let's reference this from the wizard XML:

  5. Let's create the event handler in the controller:

    In this case, we simply persist the data in the workflow and do nothing else

How to Add new sync points

In this case, you need to decide how to add new sync points that are reflected in the UI and the workflow.