Using Form Steps

in SAP’s WebFlow Engine

Jocelyn Dart, 20.03.2003, Technology Cook book

Using Form Steps in SAP’s WebFlow Engine

Table of Contents

1 WHAT ARE FORM STEPS?.............................................................................................................................3

2 BASIC PROCESS FOR CREATING FORM STEPS......................................................................................3
2.1 CREATE A DICTIONARY STRUCTURE FOR THE FORM .......................................................................................4
2.2 CREATE A WORKFLOW CONTAINER ELEMENT USING THE DICTIONARY STRUCTURE........................................4
2.3 FILL THE WORKFLOW CONTAINER ELEMENT ...................................................................................................4
2.4 INSERT THE FORM STEP OR START FORMS ENTRY ............................................................................................4
2.5 GENERATE THE FORM .....................................................................................................................................4
2.6 EXECUTING THE FORM ....................................................................................................................................5
2.6.1 Executing form steps..............................................................................................................................5
2.6.2 Executing start forms .............................................................................................................................7
2.7 EXTRACTING FORM DATA ...............................................................................................................................8
2.8 DEMONSTRATIONS OF FORMS .........................................................................................................................8
3 OPTIONS FOR EXTENDING FORM STEPS.................................................................................................8
3.1 CHANGING THE FORM LAYOUT .......................................................................................................................9
3.2 ADDING CODE TO THE FORM ...........................................................................................................................9
3.3 CREATING A NEW FORM TASK VIA REFERENCE ...............................................................................................9
3.4 CREATING HTML VERSIONS OF THE SCREEN .................................................................................................9
4 ADDITIONAL TECHNICAL INFORMATION............................................................................................10
5 LIMITATIONS OF FORM STEPS .................................................................................................................10
6 WHEN TO USE FORM STEPS.......................................................................................................................10
7 FUTURE DIRECTIONS...................................................................................................................................11

Jocelyn Dart:
Last updated: 20 February 2003 Page 2 of 11
Using Form Steps in SAP’s WebFlow Engine

1 What are FORM steps?

Form steps are a new insertable step type in SAP’s WebFlow Engine available in all WAS (Web
Application Server) system, represented by the form step icon . They enable the quick and easy
creation of simple forms. These forms can be used:
• To start a workflow
• In a work item that displays the form
• In a work item that changes the form
• In a work item that approves the form

The form can be used multiple times in the same workflow, e.g. the same form used to start the workflow,
then used in an approval step.

Forms are designed to work the same way whether executed via SAPGUI or from the web via SAPGUI
for HTML.

In addition a form can be converted to an XML document and vice versa. The resulting XML document
can then be transmitted to another system or received from another system over the web, e.g. using a
web activity step to send it via Wf-XML.

Form steps can be extended to:

• Change the layout of the form
• Add default values
• Add search helps
• Add validation
• Save data e.g. to custom tables

A significant advantage of these forms is that they include the workflow toolbox, i.e. while executing the
work item an agent can be given access to work item instructions, attachment view/creation, workflow
summary log view, etc. without having to return to the inbox. This is particularly helpful if simplified
inboxes are used, such as the Enterprise Portal’s Universal Worklist Iview, where these functions may not
be easily accessible.

Prior to the introduction of form steps, there was no standard way of producing forms that could be used
equally in SAPGUI and in web environments.

In 3.1, for web environments only, the ability to create forms using the SAPForms for HTML technique
was introduced. This technique was awkward to extended, and is essentially replaced by form steps.

Form steps are an inside-out way of producing forms where significant ABAP skills are available.

If only web forms are desired, outside-in forms can be created in web languages (such as Java and .Net)
using the WAPIs (Workflow Application Programming Interfaces) and the relevant connectors to SAP
(such as JCo and .Net Connector).

2 Basic process for creating form steps

Jocelyn Dart:
Last updated: 20 February 2003 Page 3 of 11
Using Form Steps in SAP’s WebFlow Engine

2.1 Create a dictionary structure for the form

The dictionary structure must be a flat structure, i.e. no table types or structures within structures (other
than append or include structures) can be used.

All fields to be passed from the workflow to the form step and vice versa must be included in the
structure.

2.2 Create a workflow container element using the dictionary structure

The workflow container element cannot be multiline. If used to start a workflow the workflow container
element should be marked as an “import” element.

2.3 Fill the workflow container element

When using start forms the user fills the form directly, and the data is then passed to the workflow
container element for the form.

You can also use a form step with the “Change” action to enable a user to enter the form details by
executing a work item, which then fills the workflow container element for the form.

If the workflow container element for the form is to be filled in background prior to display, then this can
be done by:
• Receiving the form in XML format, e.g. via a “web activity” step and using object method
DYNP_FORM.FROM_XML to convert it to the workflow container element for the form.
• Creating a method to fill the form from other data, e.g. FillFormFromCostCenter
• Using a container operation and virtual attribute with the same structure as the form to fill the
workflow container element.

2.4 Insert the form step or start forms entry

If using a form as a step in a workflow, insert the step type “form step” into the relevant position in the
workflow.

In a form step, nominate the form action: Display, Change, Approve or Approve with Query. These affect
the buttons displayed with the form.

• Display – No special buttons are shown.

• Change – The standard SAP “Save” button is active. The work item is not complete until “Save”
has been chosen.
• Approve – The buttons “Approve” and “Reject” are shown. The work item is not complete until
either “Approve” or “Reject” has been chosen.
• Approve with query – The buttons “Approve”, “Reject” and “Query” are shown. The work item is
not complete until either “Approve”, “Reject” or “Query” has been chosen.

If using a form to start a workflow, then the workflow container element on which the form is based must
be entered in the “Basic Data” of the workflow, “Version-Independent” section, “Start Forms” tab.

More than one form can be created for starting the same workflow.

2.5 Generate the form

Form the form step or basic data, use the Create option to start the wizard to create the form. In the
wizard you confirm which workflow container element is to be used for the form. The following will then
be generated:

Jocelyn Dart:
Last updated: 20 February 2003 Page 4 of 11
Using Form Steps in SAP’s WebFlow Engine

• A function group in the customer namespace. If no function group has yet been entered in the
“Basic Data” of the workflow (Version-Independent, Function group tab), a new function group will
be created, named after the workflow. E.g. If the workflow is WS92000001 then the function
group will be ZWS92000001. The created function group will be automatically entered in the
“Basic Data” of the workflow.
• In the function group a screen is created. The first screen created is 0001.
• The function group and screen also contain the code to import the form data from the workflow
container element, and export the form data back to the workflow container element.
• If the form is used as a start form then a transaction will be generated as well, e.g.
ZTF_WS920000010001 where WS92000001 is the workflow template id and 0001 is the screen
number.

By default, one screen is created per form. If the form is used to start a workflow and then in other steps
to approve, display or change the form then the same screen will be used for all scenarios.

A number of forms can be used in the same workflow, each form will have its own screen in the function
group.

Alternative screens for the same workflow container element can be created, i.e. by using the wizard to
create a form with a different form name but referencing the same workflow container element.

2.6 Executing the form

2.6.1 Executing form steps

Executing the work item linked to the form step results in the following tabs being displayed:

• Form fields – This contains the form screen

• Properties – This shows the status of the step (e.g. In Process), the creation date/time, the
priority, the latest end and requested start deadlines. The priority can be changed
• Workflow Toolbox - The workflow toolbox is displayed in “inplace with info” mode. This toolbox
includes: display of work item long text and ad hoc objects list, display of workflow summary log,
option to forward the work item, option to resubmit the work item, option to send a mail (this mail
can then be returned to the work item) , option to view/create attachments, option to view the
current agents of the work item.

Jocelyn Dart:
Last updated: 20 February 2003 Page 5 of 11
Using Form Steps in SAP’s WebFlow Engine

Jocelyn Dart:
Last updated: 20 February 2003 Page 6 of 11
Using Form Steps in SAP’s WebFlow Engine

2.6.2 Executing start forms

Start forms can be executed by:
• Using transaction SWUI to display all workflows that can be started ad-hoc
• Using Generic Object Services in a transaction to display all workflows that can be started ad-hoc
for a particular object instance, e.g. in the cost centre display transaction to start a workflow
based on the current cost centre.
• Use the generated transaction code shown in the “Start Forms” tab in “Basic Data”, e.g.
ZTF_WS920000010001 where WS92000001 is the workflow template and 0001 is the screen
number.

To execute a start form the user must be a possible agent of the relevant workflow template.

When started, the following tabs will be displayed:

• Form fields – This contains the form screen

• Properties – This shows the priority, latest end and requested start deadlines. New values can
be input.
• Note at start – This easily creates an initial attachment for the workflow, if desired.
• Attachments – This enables other attachments to be added to the workflow, e.g. PC documents.

Jocelyn Dart:
Last updated: 20 February 2003 Page 7 of 11
Using Form Steps in SAP’s WebFlow Engine

2.7 Extracting form data

Between steps in the workflow, the workflow container element is used to pass the form data from one
step to another.

To extract the form data for sending to an external system via XML, the object method
DYNP_FORM.TO_XML can be used. This converts the form to an XML document that can then be sent
to an external system, e.g. using a “web activity” step.

To extract the form data, e.g. to update a database, use an appropriate object method. E.g. Create an
object method such as UpdateFromForm passing the workflow container element as an input parameter.

Note that container operations and condition editors in workflow cannot be used to access individual
fields within the form structure.

2.8 Demonstrations of forms

Transaction SWUI_DEMO includes a demonstration workflow for forms, “demoforms”. This workflow
demonstrates forms used to start a workflow and to execute a work item.

3 Options for extending form steps

Jocelyn Dart:
Last updated: 20 February 2003 Page 8 of 11
Using Form Steps in SAP’s WebFlow Engine

3.1 Changing the form layout

The ABAP screen editor can be used to change the layout of the form. Both the graphical and
alphanumerical editors can be used. The screen can be accessed by:
• Pressing the change form option on the Form step
• Pressing the change form option in the Start Forms tab in Basic Data
• By accessing the function group in transaction SE80 (Repository Browser).

Fields can be hidden if desired.

New screen elements can be added if desired. The input/output/hidden settings of these elements are
completely under the control of the custom code and are not affected by the form action chosen. If the
form is to be executed in SAPGUI for HTML, care should be taken to ensure all screen elements can be
reproduced via SAPGUI for HTML.

If additional fields are added to the dictionary structure after the form has been created, the form can be
deleted and regenerated, or the fields can be manually added to the screen.

The texts for the tab names “Form fields”, “Properties” and “Workflow Toolbox” are held as numbered
texts of function group SWY_WI_EXECUTE. They can be changed via translation. However the same
texts are displayed for all forms.

3.2 Adding code to the form

The flow logic of the form screen can be changed as desired to determine whether a field should be open
for input/output or hidden, to add default values, search helps, validation of data, saving of data, etc. Any
code added is added to the function group in the customer namespace and is considered development,
not modification, for upgrade purposes.

The following should be noted:

• The work item is not passed the form. However function module
SWE_WI_GET_FROM_REQUESTER can be used to find the calling work item. Alternatively the
workflow item can be passed in the form structure.
• All the workflow/work item containers can be read, e.g. using SAP_WAPI_READ_CONTAINER,
the workflow/work item containers cannot be updated directly. Only the workflow container
element for the form can be passed back to the workflow.
• It is possible to save data to databases using the form. E.g. If lists needed to be entered, then the
lists could be saved to another table and the key information to access the lists passed back to
the workflow container.

Care should be taken that the standard modules IMPORT_DATA_nnnn and EXPORT_DATA_nnnn are
not removed as these contain the code to read and pass back the workflow container element for the
form.

3.3 Creating a new form task via reference

To adjust the work item text, long text, or restrict the possible agents given with the standard form tasks,
use the “Control” tab of the form step to create a new task with reference to the standard task.

The new task is created in the customer namespace. Work item subject text, long text, possible agent
assignment, etc. can then be changed.

3.4 Creating HTML versions of the screen

As form steps are executed in the web environment using an EasyWeb transaction it is possible to
replace individual screens with ITS templates. However it should be remembered that if an ITS template
is created for the form screen, only the contents of the “Form fields” tab will be affected.

Jocelyn Dart:
Last updated: 20 February 2003 Page 9 of 11
Using Form Steps in SAP’s WebFlow Engine

4 Additional technical information

The business object for forms is DYNP_FORM. All standard tasks for forms are based on this object.

When executing forms, the transaction used for SAPGUI is WI_EXECUTE. From the web the EasyWeb
transaction used is WI_EXECUTE_WEB. The code for these transactions is held in program
RSWY_WI_EXECUTE.

Screen 1000 of function group SWY_WI_EXECUTE is the main screen that controls the form fields,
properties, and workflow toolbox tabs.

5 Limitations of form steps

Forms are used in conjunction with a workflow, either to start a workflow or to execute a work item. They
cannot be used on their own outside of workflow as they rely on data being imported/exported to a
workflow.

The work item and workflow item are not passed directly to the form. It is possible to pass the workflow
item in a prior step, when using form steps rather than start forms. When using form steps, the work item
can be retrieved using function module SWE_WI_GET_FROM_REQUESTER. Once the work item or
workflow item is known, additional information can be retrieved from their containers e.g. using
SAP_WAPI_READ_CONTAINER.

During the execution of a form step, it is not possible to save any data back to the workflow container
other than via the form structure. As the form step updates the workflow container element directly, both
the work item and workflow containers are effectively locked during form execution. Even if changes are
made to the workflow container, e.g. via SAP_WAPI_WRITE_CONTAINER or similar, then when the
execution completes the container is overwritten.

To fill or extract data from the form, it is usually necessary to create a custom object method for the
purpose as container operations and condition editors cannot be used to access fields within structures.

There are only limited options for converting the form screen to an HTML page.

Only one workflow container element can be nominated per form. Only structure-based workflow
container elements can be used to create a form.

The workflow toolbox is built as part of the form execution. There is no provided way to influence what
options appear in the toolbox shown during form execution.

There are no provided options for adding additional or alternative buttons to the main execution screen for
each form action. However additional buttons can be added to the form screen itself.

A form is specific to a workflow and cannot be shared by multiple workflows, even if the function group on
which the form is based is attached to both workflows.

6 When to use form steps

Use forms when:
• Forms are to be created inside-out

Jocelyn Dart:
Last updated: 20 February 2003 Page 10 of 11
Using Form Steps in SAP’s WebFlow Engine

• ABAP skills are available for extending the form

• Forms need to work from both SAPGUI and the web equally
• Accessing the workflow toolbox is an important part of the process
• Executing via SAPGUI for HTML is acceptable
• For web execution, the SAPGUI for HTML environment is available (i.e. prior to WAS 6.30, an
ITS must be available)
• Forms need to be created quickly

7 Future directions
The form type “Form” is the only form type currently available. The form step will be used for other form
types in future. These new form types have yet to be determined.

Jocelyn Dart:
Last updated: 20 February 2003 Page 11 of 11