How-to: Create custom Unplanned function in Main Menu

Description

The most common control for customization

Add a new function to the Main menu. "Header fields" and optional "Steps" to collect

This example gives you

An new Unplanned function in the Main Menu
Three Header fields:
- Date
- Text
- Decimal
Three Steps

The unplanned workflow

Make sure the Unplanned Workflow fits your requirement.

Step 1: Defining a new Unplanned function

This part requires you to edit the Mobile Configuration Files

Add this section in the <pages> tag.

<!-- Custom -->
  <page id="MyUnplanned" type="UnplannedItemRegistration" icon="mainmenusettings">
    <title defaultValue="Titletext"/>
    <unplannedItemRegistrationConfiguration type="MyUnplanned" useRegistrationCollector="false">
      <header configurationKey="MyHeader" automaticAcceptOnOpen="true"/>
    </unplannedItemRegistrationConfiguration>
  </page>
<!-- Custom -->

Add this section to the <menuItems> tag.

<!-- Custom -->
<menuItem id="MyUnplanned" displayName="MyUnplanned" icon="mainmenusettings" alwaysEnabled="true"/>
<!-- Custom -->

Do you want this to be accesible from an existing page in the Action Menus.

Then add this section to the <actions> tag.

<...>
<actions>
  <!-- Custom -->
  <open icon="mainmenusettings" id="MyUnplanned" title="My Unplanned">
    <returnTransfer property="UnplannedItemRegistrationCompleted" to="RefreshOnResume"/>
  </open>
  <!-- Custom -->

Step 2: Define Header and header fields

Unplanned functions uses Header to determine which Steps to collect.

In this step you must define which header fields you want the user to see.

Subscribe to this event

OnGetReferenceData_OnAddHeaderConfigurations

// Step 2: Define Header and headerFields

[EventSubscriber(ObjectType::Codeunit, Codeunit::"MOB WMS Reference Data", 'OnGetReferenceData_OnAddHeaderConfigurations', '', true, true)]
    local procedure MyGetReferenceData_OnAddHeaderConfigurations(var _HeaderFields: Record "MOB HeaderField Element")
    begin
        _HeaderFields.InitConfigurationKey('MyHeader'); // Identifier for new Header - replace by your own name

// Add Header fields here
        _HeaderFields.Create_DateField(10, 'MyDate', 'Select date');

        _HeaderFields.Create_TextField(20, 'MyText', 'Enter text');
        _HeaderFields.Set_optional(true);

        _HeaderFields.Create_DecimalField(30, 'MyDecimal', 'Enter decimal');
    end;

Step 3: Return Steps to collect ^(Optional)

When the header is accepted a new request is made for which Steps to collect, called "GetRegistrationConfiguration".

In this step you must read the values header fields and define the subsequent steps.

If you want to collect steps you must set useRegistrationCollector="true" in Mobile Configuration Files.

<page>
  <unplannedItemRegistrationConfiguration type="MyUnplanned" useRegistrationCollector="true"> 
<..>

You can use the already collected header fields values for:

defining the steps still needed to be collected
setting useful default-values on the steps

Subscribe to this event

OnGetRegistrationConfiguration_OnAddSteps

// Step 3: Define Steps (optional)

[EventSubscriber(ObjectType::Codeunit, Codeunit::"MOB WMS Adhoc Registr.", 'OnGetRegistrationConfiguration_OnAddSteps', '', true, true)]
    local procedure MyOnGetRegistrationConfiguration_OnAddSteps(_RegistrationType: Text; var _HeaderFieldValues: Record "MOB NS Request Element"; var _Steps: Record "MOB Steps Element"; var _RegistrationTypeTracking: Text)
    var
        MyDate: Date;
        MyText: Text;
        MyDecimal: Decimal;
    begin
        // Handle only your own Header name
        if _RegistrationType <> 'MyUnplanned' then
            exit;

// Read the headerFields
        MyDate := _HeaderFieldValues.GetValueAsDate('MyDate');
        MyText := _HeaderFieldValues.GetValue('MyText');
        MyDecimal := _HeaderFieldValues.GetValueAsDecimal('MyDecimal');

// Add steps
        // For illustration, re-use the headerField value as default values on the steps
        _Steps.Create_DateStep(10, 'MyDateStep');
        _Steps.Set_header('MyDateStep');
        _Steps.Set_defaultValue(MyDate);

        _Steps.Create_TextStep(20, 'MyTextStep');
        _Steps.Set_defaultValue(MyText);
        _Steps.Set_header('MyTextStep');

        _Steps.Create_DecimalStep(30, 'MyDecimalStep');
        _Steps.Set_defaultValue(MyDecimal);
        _Steps.Set_header('MyDecimalStep');
    end;

Step 4: Handle posting

When the Header has been accepted and Steps collected, a final request is made to "Post" the information ("PostAdhocRegistration")

In this step you must read the collected values and post them to the database.

Run your function fra Mobile and you can inspect the Post Request directly. See View Request and Response XML and Error Call Stack

If you fail to perform Step 3, you will this error:

Post Request

<?xml version="1.0" encoding="utf-8"?>
<request name="PostAdhocRegistration" created="2020-02-14T15:24:24+01:00" xmlns="http://schemas.microsoft.com/Dynamics/Mobile/2007/04/Documents/Request">
  <requestData name="PostAdhocRegistration">
    <MyDate>14-02-2020</MyDate>
    <MyText>2</MyText>
    <MyDecimal>4</MyDecimal>
    <MyDateStep>14-02-2020</MyDateStep>
    <MyTextStep>2</MyTextStep>
    <MyDecimalStep>4</MyDecimalStep>
    <RegistrationType>MyUnplanned</RegistrationType>
  </requestData>
</request>

Subscribe to OnPostAdhocRegistrationOnCustomRegistrationType

Both Header values and Steps values are available.
The values are extracted from the _RequestValues parameter using "GetValue "functions.

[EventSubscriber(ObjectType::Codeunit, Codeunit::"MOB WMS Adhoc Registr.", 'OnPostAdhocRegistrationOnCustomRegistrationType', '', true, true)]
    local procedure MyOnPostAdhocRegistrationOnCustomRegistrationType(_RegistrationType: Text; var _RequestValues: Record "MOB NS Request Element"; var _CurrentRegistrations: Record "MOB WMS Registration"; var _SuccessMessage: Text; var _RegistrationTypeTracking: Text; var _IsHandled: Boolean)
    var
        MyDate: Date;
        MyText: Text;
        MyDecimal: Decimal;
    begin
        if _RegistrationType <> 'MyUnplanned' then
            exit;

if _IsHandled then
            exit;

        // Read _RequestValues
        MyDate := _RequestValues.GetValueAsDate('MyDateStep');
        MyText := _RequestValues.GetValue('MyTextStep');
        MyDecimal := _RequestValues.GetValueAsDecimal('MyDecimalStep');

        _SuccessMessage := StrSubstNo('Success %1 %2 %3', MyDate, MyText, MyDecimal);
        _RegistrationTypeTracking := 'Tracking info for the Document queue.';

        _IsHandled := true;
    end;