Form Posting Engine

Overview

The Forms Posting Engine [FPE] is the component of FLM that controls the posting of data captured on an interactive form into an SAP back end. FPE provides the framework to control when a form is applicable for posting. FPE also provides the facility to handle errors in posting and to repost the data as required once a potential problem has been corrected.

FPE can be run interactively in foreground or scheduled as a batch job to automatically pick up and post forms on a regular basis - but still allowing foreground intervention for problem resolution.

For details on running the FPE in the foreground see the FLM Administrators Guide.

FPE also provides the facility to display the form as it was posted inside the SAP GUI.

The Form Posting Engine (FPE) is responsible for transferring data from the Adobe form into the target application in a robust and managed way. Each form is linked through configuration to a series of 'posting adaptors' (which are implemented as function modules) in order to achieve this transfer.  Typically the FPE is set up to execute as a series of background jobs based on variants of the report /FLM/FPE_INVOKE.  Each variant can be used to select certain types of forms, or forms at certain posting statuses, such as those never before run or those already in error.

Whilst running, the system processes each form in turn until no more forms are available, at which point the job stops.  Forms that fail in some way are set to a 'Rejected' status by default, you could then configure a new variant of the FPE job to pick these up and try again. Standard behavior is that in order for each form in the job to be considered a success, every adaptor must work successfully.  If this happens then the system executes a 'Commit Work' command after each form.  It is possible to configure the system to behave differently from this though as described in the activity sections below.

For example the system could be configured to execute a 'Commit Work' immediately after each adaptor runs successfully, or a 'Rollback Work' if the adaptor fails.

Forms that run successfully cannot be re-run whereas forms that fail can be rerun.  During a rerun job, standard behavior causes each adaptor not to be re-executed only if a) it worked successfully and b) was committed in a previous run.  You can override this behavior with the 'ReRun mode' switch as described below  Note// the Rerun Mode switch does not influence whether the overall job is rerun, only whether an individual adaptor is executed within an already re-running job.

FPE processing is controlled by two tables, 'Valid Statuses' and 'Posting Adapters'.

Valid Statuses

For each form status, the following functionality can be configured:

Posting Ok

You must mark this checkbox for any status you wish to run the FPE for. It is a pre-requisite for any FPE processing of this form.

No Fail

Forms marked as 'No Fail' produce a different return code (8) in the event of the FPE job failing.  This distinguishes them from normal FPE failures which are given the return code 4.  These are known as 'Partial' and 'Rejected' forms respectively.  By setting a form to 'No fail' you can therefore exclude it from the variant of the FPE job you set up to re-process Rejected forms.

Action on Success or Fail

After an FPE run has finished you can specify that the form is further processed by FLM automatically.  In these fields you specify the Form Action that is applied to the form in the event that the form either fails (return code 4 only, see 'No Fail' section above) or succeeds.  It is not permissible to have the FPE execute synchronously for these Form Actions, otherwise a recursive situation may result.

E-mail Alert Required

If you mark this checkbox the system will dispatch an email to an administrator in the event of a Rejection (return code 4).  The subsequent fields hold the target email address and the text objects for the title and body of the email.

E-mail Alert details

The administrator e-mail adress is entered, and standard texts for the e-mail subject and e-mail body.

Posting Adapters

 The following configuration options are available:

Step

This is the step number of the adaptor and indicates in which sequence the adaptors will be executed.

Req (optional)

This is the adaptor 'Requirement'; this is a small ABAP routine that causes the adaptor be executed conditionally upon its own return code. Specifically the requirement must return a return code of zero or the adaptor will be skipped.  Certain requirements are shipped with the system, and you are free to add your own as required.

Posting Adaptor

Here you enter the name of the posting adaptor.  The name must end in the convention _XXX where XXX is the lowest SAP release that this adaptor supports.  If you are not sure, end the adaptor _700.

Step Fn (optional)

This is the 'Step Function' that causes processing to conditionally jump to another adaptor in the set.  Similar to the Requirement above, certain step functions are supplied with the system and you are free to add your own as required.

Commit (optional)(295+ adaptors only)

If this checkbox is marked, the system will send an immediate 'Commit Work' command provided that the adaptor returned a success code (0). Because the command is sent before the next adaptor runs, it means that the work done can not be rolled back.

Failure Mode (optional) (295+ adaptors only)

This switch determines how the system reacts in the event that the adaptor returns a non-zero return code.  You have 3 choices:

  • Do nothing.  Here the system continues processing the next adaptor
  • Rollback work.  Here the system sends a 'Rollback Work' command and then continues processing the next adaptor.
  • Rollback and terminate.  Here the system sends a 'Rollback Work' command and then stops any further processing

Ignore Errors (optional) (295+ adaptors only)

If this checkbox is marked then the return code of this adaptor does not contribute towards the determination of the overall success or failure of the FPE run.  Example:

There is only one adaptor and the 'ignore errors' flag is set.  When the FPE job runs the adaptor fails and sends back a return code of 4.  This is ignored by the FPE framework and so the overall return code is set to zero, the job considered a success and is therefore not available for reprocessing.

ReRun Mode (optional) (295+ adaptors only)

This switch influences whether, during a rerun scenario, a particular adaptor is executed. It does not in any way influence whether the overall form is available for rerun, that is purely a function of the return codes of the individual adaptors during the previous run and the 'ignore errors' flag. There are 3 choices:

  • Standard.  Adaptors are rerun unless they returned a zero return code AND were committed during any previous FPE run of this form.
  • Always Rerun.
  • Never Rerun.

RFC Dest (optional)

The behavior of this switch depends on the version of the adaptors you are running:

Pre-295.  At these releases if you enter an RFC destination here, then the FPE expects that the posting adaptor has been implemented on a remote system and hence will execute it on the remote system.

295+.  At these releases posting adaptors are always implemented locally.  However, this RFC destination is supplied as a parameter to the posting adaptor such that a remote function can be executed on a remote system if required.

Important Note: the execution of any remote function module from an SAP system causes a 'Commit Work' command to be sent both locally and remotely, and hence the ability of FPE to rollback any subsequent failures is removed.

 Posting Adapter Functions

Form data is posted into a back end SAP system by normal SAP function module developed in SE37 like any other function. Its is required to use a predefined set of import and export parameters.

The import parameters are:

IM_FORMS_DATA.  An internal table of the data extracted from the form so that the function can extract / convert it prior to a posting attempt.

IM_STEP.  The sequence number passed in from the control table /FLM/FPE_CNTRL. Its is possible for one posting function to be invoked multiple times with each call being distinguished by a change in sequence number. One posting function could therfore be written to perform multiple functions. This is not generally used and is usually 0.

IM_DIALOGUE_MODE.  Some posting functions can be run interactively to facilitate the ease of identifying a posting problem. To allow this the dialogue mode is passed into the adaptor from the /FLM/FPE_INVOKE program selection screen. [Note that this facility is not possible for postings into SAP by non screen related functions such as BAPI’s.]

IM_FPE.  The form instance data: the table row of table /FLM/FPE that stores the index to the form data and current status information.

IM_STATUS_T. A table showing the detailed statuses of each posting adapter step in the current and previous run.

IM_RFC_DEST.  The RFC destination configured in SM59 for remote function calls.

The export parameters are:

EX_POSTED_DOC.  The document number or reference related to a successful posting is assigned to this parameter.

EX_SUBRC.  A return code to control whether the posting was successful or not.

EX_NO_POST_ATTEMPT.  A flag that indicates to the FPE framework that no attempt to post was made – so neither success or failure.

CH_RETURN. A table of messages in which a processing log can be written.  Typically all BAPI return messages will be appended into this table.

Here is a simple posting adapter to update a custom table:

1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
12:
13:
14:
15:
16:
17:
18:
19:
20:
21:
22:
23:
24:
25:
26:
27:
28:
29:
30:
31:
32:
33:
34:
35:
36:
37:
38:
39:
40:
41:
42:
43:
44:
45:
46:
47:
48:
49:
50:
51:
52:
53:
54:
55:
56:
57:
58:
59:
FUNCTION z_feedback_form_post_700.
*"----------------------------------------------------------------------
*"*"Local Interface:
*"  IMPORTING
*"     VALUE(IM_FORMS_DATA) TYPE  /FLM/XML_TAB_T
*"     VALUE(IM_STEP) TYPE  /FLM/PROCESS_SEQ
*"     VALUE(IM_DIALOGUE_MODE) TYPE  CHAR1
*"     VALUE(IM_FPE) TYPE  /FLM/FPE
*"     VALUE(IM_STATUS_T) TYPE  /FLM/FPE_STATUS_T
*"     VALUE(IM_RFCDEST) TYPE  /FLM/FPE_RFCDEST
*"  EXPORTING
*"     VALUE(EX_POSTED_DOC) TYPE  /FLM/PDOC
*"     VALUE(EX_SUBRC) TYPE  SYSUBRC
*"     VALUE(EX_NO_POST_ATTEMPT) TYPE  FLAG
*"  CHANGING
*"     REFERENCE(CH_RETURN) TYPE  /FLM/MESS_T
*"----------------------------------------------------------------------

  DATA: ls_forms_data      TYPE /flm/xml_tab,
        ls_event_responses TYPE zevent_responses.

  LOOP AT im_forms_data INTO ls_forms_data.

    CASE ls_forms_data-name.

      WHEN 'TXT_EVENT_ID'.        ls_event_responses-txt_event_id = ls_forms_data-value.
      WHEN 'TXT_ATTENDEE'.        ls_event_responses-txt_attendee = ls_forms_data-value.
      WHEN 'TXT_ATTENDEE_EMAILD'. ls_event_responses-txt_attendee_ema = ls_forms_data-value.
      WHEN 'NUM_OVERALL_EXP'.     ls_event_responses-num_overall_exp = ls_forms_data-value.
      WHEN 'NUM_OVERALL_CONT'.    ls_event_responses-num_overall_cont = ls_forms_data-value.
      WHEN 'CB_HANA_EVAL'.        ls_event_responses-cb_hana_eval = ls_forms_data-value.
      WHEN 'CB_HANA_PLAN'.        ls_event_responses-cb_hana_plan = ls_forms_data-value.
      WHEN 'NUM_OVERALL_CUST'.    ls_event_responses-num_overall_cust = ls_forms_data-value.
      WHEN 'NUM_Q1_RESP'.         ls_event_responses-num_q1_resp = ls_forms_data-value.
      WHEN 'NUM_Q2_RESP'.         ls_event_responses-num_q2_resp = ls_forms_data-value.
      WHEN 'NUM_Q3_RESP'.         ls_event_responses-num_q3_resp = ls_forms_data-value.
      WHEN 'NUM_Q4_RESP'.         ls_event_responses-num_q4_resp = ls_forms_data-value.
      WHEN 'NUM_Q5_RESP'.         ls_event_responses-num_q5_resp = ls_forms_data-value.
      WHEN 'NUM_Q6_RESP'.         ls_event_responses-num_q6_resp = ls_forms_data-value.
      WHEN 'NUM_Q7_RESP'.         ls_event_responses-num_q7_resp = ls_forms_data-value.
      WHEN 'NUM_Q8_RESP'.         ls_event_responses-num_q8_resp = ls_forms_data-value.
      WHEN 'NUM_Q9_RESP'.         ls_event_responses-num_q9_resp = ls_forms_data-value.
      WHEN 'NUM_CATERING'.        ls_event_responses-num_catering = ls_forms_data-value.
      WHEN 'TXT_TOPICS'.          ls_event_responses-txt_topics = ls_forms_data-value.
      WHEN 'TXT_ASSISTANCE'.      ls_event_responses-txt_assistance = ls_forms_data-value.
      WHEN 'TXT_RECOMMEND'.       ls_event_responses-txt_recommend = ls_forms_data-value.

    ENDCASE.

  ENDLOOP.

  ls_event_responses = im_fpe-id.

  INSERT zevent_responses FROM ls_event_responses.
*
  ex_subrc = sy-subrc.
  ex_posted_doc = im_fpe-id.
*
ENDFUNCTION.

Sample Adaptors

Releases up to 290 sp4:

A sample adaptor called /FLM/FPE_SAMPLE_470 is delivered with the system.  This function module has the correct interface to work with the forms posting engine.

Release 295:

A sample adaptor called /FLM/FPE_SAMPLE_295_700 is delivered with the system.  This function module has the correct interface to work with the forms posting engine.

The name of the posting adaptor function module must end in a _XXX format, where XXX is the lowest SAP system level at which the posting adaptor is designed to run.

Invoking FPE

FPE is normally scheduled as a series of background jobs (program /FLM/FPE_INVOKE) or can be run in the foreground using transaction  /FLM/FPE.