Skip to main content
You are here: Integrations

SSAM+Forms User Guide

Table of Contents

1 Introduction

1.1 Overview

1.2 Purpose

1.3 Scope

1.4 Prerequisites

2 Mirata Core Metadata Component for SSAM

2.1 Component Installation

2.2 Component Functionality Summary

2.3 Metadata Override Summary

2.4 Metadata Interface Summary

3 Mirata Integration Metadata Component for SSAM

3.1 Component Installation

3.2 Metadata Override Summary

3.3 Metadata Functionality Summary

4 Mirata Form Definition Compatibility

4.1 Integration Data Mappings

4.2 Form Fields

4.3 Header Fields

4.4 Workflow Transitions

5 Appendix A: Acronyms, Abbreviations & Definitions

1) Introduction

1.1 Overview

Mirata Forms functionality can be embedded into the SAP Service Asset Manager (SSAM) mobile application. This is accomplished using a branded MDK client application that utilizes a Mirata MDK extension control and using the Mirata metadata components for SSAM.

Two metadata components are provided by Mirata for use SSAM. The Mirata Core Metadata Component enables the following functionality:

  • Synchronization of Mirata Forms data with the cloud-based Mirata customer API endpoint

  • Creation and management of Mirata Forms OData entities and entity sets

  • An MDK Page definition utilized by the Mirata MDK Extension Control to present Mirata Forms within the SSAM mobile application

  • Mirata error logging and reporting

The Core component is managed and supported by Mirata and its contents should not be modified. Otherwise, improper or unexpected Mirata Forms functionality may result from unauthorized modifications to the metadata of the Core component.  

The Mirata Integration Metadata Component provides a fully functional example of how Mirata Forms can be embedded in SSAM and integrated with SSAM business logic. However, it is by no means the only possible integration approach. The primary purpose of the Integration component is to allow for quickly prototyping of a solution involving Mirata Forms embedded in SSAM without requiring any SAP server-side customizations or modifications to the SSAM mobile application’s configuration in the “Mobile Add-On for SAP ERP” (also referred to as the “Config Panel”). When implementing a custom solution that embeds Mirata Forms in SSAM, any of metadata files provided in the Integration metadata component can be used “as is” or be modified and enhanced as required.

1.2 Purpose

This document details how to incorporate the Mirata SSAM metadata components into a SSAM 2405 metadata project. It also provides a description or overview of the individual files in each metadata component.

1.3 Scope

This documentation assumes the Mirata SSAM metadata components will be integrated with a standard (i.e.- unmodified) version of SSAM. See section “1.4 Prerequisites” below for the specific SSAM metadata version required. 

Each Mirata SSAM metadata component utilizes a “Component Integration Metadata” (CIM) file to override standard SSAM metadata files. Each metadata file listed in the Mirata component CIM files is modified version of the corresponding standard SSAM metadata file. If an existing SSAM metadata project contains modifications, either by incorporating other CIM-based components or by direct modification of the standard SSAM metadata files (not recommended by SAP), then extra analysis steps must first be performed before adding the Mirata metadata components to a customized SSAM metadata project.

Specifically, it must be determined if any of the standard SSAM metadata files listed in the Mirata components’ CIM files are also referenced by another component’s CIM file (or have been directly modified in the standard SSAM metadata project). If this is found to the case, then the corresponding override file from the other component (or the modified file from the standard SSAM project) must be manually merged with the Mirata component’s metadata file by an MDK implementer and injected into back into the customized SSAM project using a new component and associated CIM file.

1.4 Prerequisites

For installing the Mirata SSAM metadata components, the following are prerequisites:

  • SSAM 2405 PL04 (2405.0.4) metadata

  • A branded MDK client application project

For using the Mirata SSAM metadata components, the following are prerequisites:

  • A Mirata-branded MDK client built with the Mirata MDK Extension Control (and supporting Mirata software components).

    • See the “Mirata-branded MDK Client for SSAM 2405 User Guide”.

  • The Mirata “Forms OData Interface Layer” (FOIL) BTP application has been installed and configured in the BTP subaccount space that is hosting the Mirata Forms-enabled SSAM 2405 mobile application.

    • See the Mirata “Forms OData Interface Layer User Guide”.

  • FOIL XSUAA service configuration data has been shared with Mirata to establish an SSO trust relationship with Mirata

    • See the Mirata “Forms OData Interface Layer User Guide”.

  • A Mirata “Mobile Connectivity Destination” has been added to the Mirata Forms-enabled SSAM 2405 mobile application configuration in BTP Mobile Services.

    • See the Mirata “Forms OData Interface Layer User Guide”.

2) Mirata Core Metadata Component for SSAM

The Mirata Core Metadata Component provides metadata components that are critical to enabling the embedding of Mirata Form in SAP Service and Asset manager. The Core Metadata Component is maintained by Mirata and its contents should not be modified in any manner; otherwise, improper and/or unexpected SSAM or Mirata Forms functionally may result.

2.1 Component Installation

Installing the Mirata Core Metadata Component is required when embedding Mirata Forms in the SSAM mobile application. This section details how to incorporate the Mirata Core Metadata Component into an existing branded MDK client project’s directory structure.

This documentation uses “SSAM.mdkproject” as the name of the branded MDK client project directory. Your project directory name may be different, and if so, should be substituted accordingly in the steps below.

  1. In the SSAM.mdkproject/metadata directory, create a subdirectory ssam-metadata that will hold the standard SSAM metadata.

    • Note that any name of your choosing may be used for this subdirectory and ssam-metadata is only a suggestion.

  2. Move all existing standard SSAM metadata files and directories currently in the SSAM.mdkproject/metadata directory into the SSAM.mdkproject/metadata/ssam-metadata subdirectory.

  3. Edit the SSAM.mdkproject/MDKProject.json file and add the following key/value pair to the existing JSON object defined in the file:

    • "BaseProject": "ssam-metadata"

  4. Create the subdirectory forms-ssam-core-metadata under the directory SSAM.mdkproject/metadata and expand the ssam-2405-forms-core-component-<variant>-<version>.zip archive into it.

  5. Copy the hidden file…
    SSAM.mdkproject/metadata/forms-ssam-core-metadata/.ssam/.01-MirataFormsCoreComponents.cim
    …to…

    SSAM.mdkproject/metadata/ssam-metadata/01-MirataFormsCoreComponents.cim

    • Note that the CIM file must be renamed when copied by removing the leading period (.)

  6. Delete the hidden subdirectory…

    • SSAM.mdkproject/metadata/forms-ssam-core-metadata/.ssam

  7. A single modification must be made to the base SSAM metadata. In the newly created SSAM.mdkproject/metadata/ssam-metadata directory, edit the Application.app file. The value of the “_SchemaVersion” key must be a value equal to or greater than “23.12”

    • This version of the MDK schema allows fragments and styles to be overridden using a CIM file.

If the “_SchemaVersion” key is not set to a value of “23.12” (or higher), an error will be incurred when the “SSAM + Mirata Forms” metadata is “bundled” during the branded MDK client build process’s execution.

Execute a new build of the branded MDK client as per usual, ensuring that no new build-time errors are incurred.

2.2 Component Functionality Summary

Once the Mirata Core Metadata Component has been integrated into your existing SSAM metadata project, the following new synchronization session functionality will be implemented. During the "initial sync" of the application (i.e.- the first sync performed after SSAM is newly installed or after a new user has initially logged into SSAM after a “Reset” has been performed), a "Retrieving Mirata Forms data (<status>…)" progress message will be displayed during the Mirata Forms portion of the synchronization session (see Figure 1).  During user-invoked synchronization sessions, a "toast-style" message will be displayed when the Mirata portion of the synchronization session begins, a "banner-style" message will provide status updates during the execution of the Mirata synchronization (see Figure 2) and another "toast-style" message will be displayed when the Mirata portion of the synchronization session completes.

2.3 Metadata Override Summary

This section provides details on the SSAM metadata files that are overridden by the Mirata Core Metadata Component.

2.3.1 Rules

2.3.1.1 ApplicationOnSync.js

  • SSAM file:

    • Rules/ApplicationEvents/ApplicationOnSync.js

  • Functional summary:

    • Implements the SSAM synchronization session functionality when the SSAM “sync” toolbar button is selected.

  • Component override file:

    • Rules/ApplicationEvents/ApplicationOnSyncWithForms.js

  • Override summary:

    • Once the SSAM portion of the synchronization session functionality has completed successfully, the Mirata synchronization activities are initiated.

2.3.1.2 DownloadActionsOrRulesSequence.js

  • SSAM file:

    • Rules/OData/Download/DownloadActionsOrRulesSequence.js

  • Functional summary:

    • Defines the execution sequence of the rules and actions that perform the download of data from various application data sources.

  • Component override file:

    • Rules/OData/Download/ApplicationOnSyncWithForms.js

  • Override summary:

    • After the SSAM-managed OData entity sets have been initialized (if needed) and the download of the data required to populate each entity set has been initiated and completed, the same functionality is then performed for the Mirata-managed OData entity sets.

2.3.2 i18n (Internationalization)

2.3.2.1 i18n.properties

  • SSAM file:

    • i18n/i18n.properties

  • Functional summary:

    • Defines name/value pairs that are used to present application text in one of several supported languages.

      • Each “name” is a unique identifier for the entry.

      • The value is the “default” text that will be displayed in place of the corresponding code when referenced in the SSAM metadata, but only if a specific language to display has not been specified.

      • The language used for the default value text is English.

  • Component override file:

    • i18n/i18n.properties

  • Override summary:

    • Adds name/value pairs that are referenced by Mirata Core Metadata Component logic.

    • The names of all the Mirata-specific additions are prefaced with “zforms_” and are defined together in a section located at the top of the file.

2.3.2.3 i18n_en.properties

  • SSAM file:

    • i18n/i18n_en.properties

  • Functional summary:

    • Defines English text for the values of all the name/value pairs defined in the base internationalization file (i18n.properties)

    • The values in this file are displayed in place of the corresponding code when referenced in the SSAM metadata, but only when English has been designated as the application language to display.

  • Component override file:

    • i18n/i18n_en.properties

  • Override summary:

    • Adds name/value pairs that are referenced by Mirata Core Metadata Component logic.

    • The names of all the Mirata-specific additions are prefaced with “zforms_” and are defined together in a section located near the top of the file.

    • A small number of SAP-specific entries are overridden.

      • The overridden entries are referenced during the execution of the SSAM synchronization session.

      • The values of the overridden entries add text to denote that the referenced action is part of the SAP portion of the synchronization action. Corresponding messages are displayed by Mirata Core Metadata Component logic that denote the referenced action is part of the Mirata portion of the synchronization action.

      • When referencing a specific code in a language-specific i18n file, MDK uses a "first found" algorithm. That is, if an i18n has multiple entries defined with the same “name”, the first line found with a matching name is used.

      • The overridden SAP-specific entries are defined together in a section located at the top of the file.

2.3.3 Styles

2.3.3.1 Styles.less

  • SSAM file:

    • Styles/Styles.less

  • Functional summary:

    • Defines CSS-based “styles” that can be applied to various MDK metadata components when the mobile device is configured to display its overall UI in “normal” or “light” (i.e.- not “dark”) mode.

  • Component override file:

    • Styles/Styles.less

  • Override summary:

    • Adds two new styles that are referenced by the Mirata Core Metadata Component’s FormsExtension.page (see section 2.4.1).

    • The new styles are defined as the last entries in the file.

2.3.3.2 Styles.dark.less

  • SSAM file:

    • Styles/Styles.dark.less

  • Functional summary:

    • Defines CSS-based “styles” that can be applied to various MDK metadata components when the mobile device is configured to display its overall UI in “dark” mode.

  • Component override file:

    • Styles/Styles.dark.less

  • Override summary:

    • Adds two new styles that are referenced by the Mirata Core Metadata Component’s FormsExtension.page (see section 2.4.1).

    • The new styles are defined as the last entries in the file.

2.4 Metadata Interface Summary

This section details how to interface with definitions in the Mirata Core Metadata Component that can be referenced by other metadata components in your SSAM metadata project.

2.4.1 Pages

2.4.1.1 Component path: Pages/Extensions/FormsExtension.page

The MDK Page definition that is utilizes the Mirata MDK Extension Control to present Mirata Forms. The Mirata MDK Extension Control, along with the Mirata Embedded Software, must be built in the branded MDK client used to run the “SSAM + Mirata Forms” mobile application.

This page requires three key/value pairs be defined in the current context’s “binding object”, as follows:

  • FormId (String)

    • The “ID” property value of the Mirata Form to display

  • FormSubmissionQueryOptions (String)

    • A Mirata form submission records a “snapshot” of the data collected by a given Mirata form instance, along with metadata that records the operation state of the form at the time the submission was created.

      • Mirata form submissions are typically created when the user performs a “save” operation on a form.

      •  Mirata form submissions are recorded as entities in the Mirata Submission OData entity set.

    • This parameter defines the OData query options required to query the Mirata Submission OData entity set for any existing submission entities associated with the form being rendered.

    • When Mirata Forms is embedded in SSAM, the submissions of a given Mirata form instance are typically associated with a SSAM business object (such as a work order, operation, equipment, etc.).

    • The “Header Info” of a Mirata form definition can be leveraged to record this association with a SSAM business object. Each “Header Info” field and associated value is recorded as a name/value pair in a JavaScript object that, in turn, is saved in a serialized manner in a string property of a Mirata Submission OData entity. This “Header Info” data can then be referenced in an OData query run against the Mirata Submission OData entity set.

  • ContextData (String)

    • If an error should occur presenting a Mirata form, this parameter’s value is used to help identify and define the application context that resulted in the error condition in the data sent to the Mirata error logging facility.

    • A serialized JavaScript object can be used to reflect multiple contextual data items.

2.4.2 Rules

2.4.2.1 LogError.js

Component path: MirataFormsCoreComponents/Rules/Forms/LogError.js

The MDK Rule definition that sends error information to the Mirata error reporting facility that can be view using the “Log Info” feature of the Mirata Admin Tool, and to the MDK logging facility.

When called from another rule, this LogError rule takes two parameters, as follows:

  • context (required)

    • A context-specific subclass of the MDK ClientAPI class.

    • Provided by the MDK architecture when it executes a rule.

    • Can also be passed as a parameter to a rule that is called by another rule.

  • err (required)

    • Either a JavaScript Error object or a string describing an error condition

      • Typically, this is a JavaScript Error object caught by a try/catch block

      • While a string describing an error condition may be provided, it is recommended that a JavaScript Error object be constructed using the error text at the point the error condition was detected so that the stack trace associated with the Error object reflects the origin of the error.

  • data (optional)

    • A JavaScript object with the following structure:
      {
        component: “<string describing the functional component/context>”,
        mdkInfo: {
          errorInfo: “<string providing supplementary error details>”
        }
      }

    • The component and mdkInfo object keys are both individually optional; however, one or both must be defined.

If the mdkInfo key is defined, its value must an object with the (required) errorInfo key/value pair defined.

2.4.3 Images

2.4.3.1 mirata.light.png, mirata.dark.png, mirata.android.light.png, mirata.android.dark.png

A collection of four image files that together implement an image of the Mirata-stylized “M” logo. This image can be associated with an item in the “action bar” area of an MDK page that is used to navigate to the MDK page definition used to display a Mirata form.

The “mirata.*.png” files are used to render the image on the iOS platform, while the “mirata.android.*.png” files are used to render the image on the Android platform. The “*.light.png” files are used to render the image when the device’s system UI is configured to display in standard (or “light”) mode, while the “*.dark.png” files are used to render the image when the device’s system UI is configured to display in “dark” mode.

When the individual files are reference in MDK metadata logic, the “light” and “dark” terms are not used! For example: “mirata.png” and “mirata.android.png”

To facilitate the platform-specific use of the individual image files, the MDK “platform specific binding” directive (PLT)  is used…

$(PLT, <value for iOS>, <value for Android>, <value for Web>)

… and specifically …

$(PLT, /MirataFormsCoreComponents/Images/mirata.png, /MirataFormsCoreComponents/Images/mirata.android.png)

3) Mirata Integration Metadata Component for SSAM

Installing the Mirata Integration Metadata Component is not required when embedding Mirata Forms in the SSAM mobile application. However, it can be installed to prototype Mirata Forms functionality embedded in SSAM.

The Mirata Integration Metadata Component allows for an instance of a Mirata Form to be associated with an operation of a work order. How this is accomplished is simplistic… the unique ID of the form is manually recorded in the “notes” (i.e.- “long text”) property of the work order operation. This approach provides a means to quickly enable the embedding of Mirata Forms into SSAM for prototyping and proof-of-concept purposes. However, this approach is not recommended for “production” implementations because…

  • Associating a Mirata Form with a work order operation is a manual process in all scenarios.

  • The Mirata Form ID in the work order operation notes is not protected and can be easily altered.

A better approach would be to utilize an unused field available in Work Order Operation SAP table to hold the associated Mirata Form ID, or if no field is available, extend the table to add the necessary field. This will allow for the relationship between a Mirata Form and a work order operation to be more tightly controlled, as the field could be configured to be read-only or hidden in the SSAM application screen(s) that display work order operation details.

Implementation notes:

  • The Mirata Integration Metadata Component has a dependency on the Mirata Core Metadata Component having already been installed in the SSAM metadata project.

  • The Mirata Integration metadata assumes that the SAP server has been configured to use a “Work Order Header” assignment model.

  • Certain specific configurations must be implemented in the Mirata Form definitions that are associated with Work Order Operations (see section TODO).

3.1 Component Installation

  1. Create the subdirectory forms-ssam-integration-metadata under the directory SSAM.mdkproject/metadata and expand the ssam-2405-forms-integration-component-<variant>-<version>.zip archive into it.

  2. Copy the hidden file …
    SSAM.mdkproject/metadata/forms-ssam-integration-metadata/.ssam/.02-MirataFormsIntegrationComponents.cim …to…
    SSAM.mdkproject/metadata/ssam-metadata/02-MirataFormsIntegrationComponents.cim

    ...to...

    SSAM.mdkproject/metadata/ssam-metadata/02-MirataFormsIntegrationComponents.cim

    • Note that the CIM file must be renamed when copied by removing the leading period (.) character

  3. Delete the hidden subdirectory…
    SSAM.mdkproject/metadata/forms-ssam-integration-metadata/.ssam

Execute a build of your branded MDK client and ensure that no new build errors are incurred.

3.2 Metadata Override Summary

This section provides details on the SSAM metadata components that are overridden by a Mirata Integration Metadata Component.

3.2.1 Page Fragments

3.2.1.1 WorkOrderOperationActionbarItems.fragment

  • SSAM file:

    • Pages/Fragments/WorkOrder/WorkOrderOperations/ WorkOrderOperationActionbarItems.fragment

  • Functional summary:

    • A page fragment that defines the items that appear in the “action bar” area of the “Work Order Operation Detail” page. 

  • Component override file:

    • Pages/Fragments/WorkOrder/WorkOrderOperations/ WorkOrderOperationActionbarItems.fragment

  • Override summary:

    • Adds a new “action bar” item that when pressed navigates to an MDK page (see section 2.4.1.1) that displays the Mirata form associated with work order operation in context.

    • The action bar item displays the Mirata “M” logo image from the Mirata Core Integration Metadata Component (see section 2.4.3.1).

3.2.2 Rules

3.2.2.1 NoteLibrary.js

  • SSAM file:

    • Rules/Notes/NoteLibrary.js

  • Functional summary:

    • Implements classes, each composed of a collection of static methods, that collectively provide an interface for adding to and editing the “notes” (i.e.- “long text”) property that is commonly associated with various types of SAP business objects.

  • Component override file:

    • Rules/Notes/NoteLibrary.js

  • Override summary:

    • Adds static methods to the existing classes that facilitate adding to, and editing, the “notes” property data of a work order operation using text that originates from a Mirata form.

3.2.2.2 OperationCompleteStatus.js

  • SSAM file:

    • Rules/Operations/MobileStatus/OperationCompleteStatus.js

  • Functional summary:

    • Implements logic to “complete” a work order operation.

  • Component override file:

    • Rules/Operations/MobileStatus/OperationCompleteStatus.js

  • Override summary:

Imports the overridden version of the OperationMobileStatusLibrary class which implements a modified version of the completeOperation method, that in turn, validates that the Mirata form associated with a form-enabled operation has “mobile complete” status before the operation can be set to complete status.

3.2.2.3 OperationConfirmStatus.js

  • SSAM file:

    • Rules/Operations/MobileStatus/OperationConfirmStatus.js

  • Functional summary:

    • Implements logic to “confirm” a work order operation.

  • Component override file:

    • Rules/Operations/MobileStatus/OperationConfirmStatus.js

  • Override summary:

Imports the overridden version of the OperationMobileStatusLibrary class which implements a modified version of the completeOperation method, that in turn, validates that the Mirata form associated with a form-enabled operation has “mobile complete” status before the operation can be set to confirmed status.

3.2.2.4 ConfirmAllButtonOnPress.js

  • SSAM file:

    • Rules/Operations/OperationsObjectCardCollection/ConfirmAllButtonOnPress.js

  • Functional summary:

    • Implements logic to “confirm” all operations associated with a work order and is called when the “Confirm All” (operations) button on the SSAM “Work Order Details” screen is pressed.

  • Component override file:

    • Rules/Operations/MobileStatus/OperationConfirmStatus.js

  • Override summary:

    • For each operation being confirmed, if the operation is form-enabled, validates that the associated Mirata form has “mobile complete” status; if not, the operation is not confirmed and the user is notified, but all other qualifying operations are still allowed to be confirmed.

3.2.2.5 OperationMobileStatusLibrary.js

  • SSAM file:

    • Rules/Operations/MobileStatus/OperationMobileStatusLibrary.js

  • Functional summary:

    • A JavaScript class composed of a collection of static methods, that implement SSAM application functionality involved with changing the status of a work order operation.

  • Component override file:

    • Rules/Operations/MobileStatus/OperationMobileStatusLibrary.js

  • Override summary:

    • Adds a static method to ensure that a Mirata form instance associated with a Mirata form-enabled work order operation has been completed before the operation itself can be completed/confirmed.

3.3 Metadata Functionality Summary

3.3.1 Actions

3.3.1.1 FormsExtensionPageNav.action

  • Component Path: Actions/Forms/Navigation

3.2.2 Presents the FormsExtension.page defined in the Mirata Core Metadata Component (see section 2.4.1Pages

  • FormsExtension.page).

3.3.2.1 FormsListViewPageNav.action

  • Path: Actions/Forms/Navigation

  • Presents the FormsListView.page (see section 3.3.3.1)

3.3.2.2 NotesCreateOnWOOperationForMirataForm.action

  • Component Path: Actions/Forms/Notes

  • Creates an entity in the SSAM MyWorkOrderOperationLongTexts entity set.

  • Enables a Mirata form to add text the notes (i.e.- “long text”) property of a work order operation.

3.3.2.3 NotesUpdateOnWOOperationForMirataForm.action

  • Component Path: Actions/Forms/Notes

  • Updates an existing entity in the SSAM MyWorkOrderOperationLongTexts entity set.

  • Enables a Mirata form to update text previously added to the notes (i.e.- “long text”) property of a work order operation.

3.3.2.4 ToastMessage.action

  • Component Path: Actions/UserInterface

  • Presents notification text to the user interface that is automatically dismissed after a configurable time period; similar in style to the Android platform’s “toast message”.

3.3.3 Pages

  • Component Path: Pages/Forms

  • An MDK Page definition that presents a list of Mirata Forms for the user to select from.

    • This list is presented as a modal dialog-style window

    • Each list item presents the “name” and “descriptions” properties of a Mirata form.

    • Each list item also records the associated Mirata form’s ID (but does not display it)

  • When a list item is selected, the associated Mirata form ID is passed as a parameter to a rule that, in turn, navigate to a page that displays the Mirata form associated with the form ID passed.

3.3.4 Rules

3.3.4.1 GetFormInfoList.js

  • Component Path: Rules/Forms/FormListView/

  • Retrieves a list of Mirata form information from the "notes" property of the work order operation in context.

3.3.4.2 FormsLibrary.js

  • Component Path: Rules/Forms/Library/

  • A JavaScript class composed of static methods that implement various utility functions that provide assistance with managing embedded Mirata forms.

3.3.4.3 FormsExtensionPageNavFromFormsListViewPage.js

  • Component Path: Rules/Forms/Navigation/

  • Closes the Forms List View page and navigates to the Forms Extension page to display the Mirata form that was selected by the user on the Forms List View page.

3.3.4.4 FormsExtensionPageNavFromWorkOrderOperationDetailsPage.js

  • Component Path: Rules/Forms/Navigation/

  • Navigates to the Forms Extension page from the Work Order Operation Details Page.

  • Acquires the data required by the Forms Extension page to display the Mirata form and passes it as data bound to the Forms Extension page's navigation action.

3.3.4.5 FormsToolbarIconPressEventHandler.js

  • Component Path: Rules/Forms/Navigation/

  • Handles the press event for the Mirata Forms toolbar icon on the Work Order Operation Details page.

  • If the work order operation in context is form list-enabled and a corresponding form submission does not already exist, navigation to the Forms List View page is performed. Otherwise, navigation to the Forms Extension page is performed.

3.3.4.6 AddOperationNoteText.js

  • Component Path: Rules/Forms/Notes/

  • Adds text to the notes (i.e. - "long text") property of the work order operation currently in context.

3.3.4.7 NoteCreateFromFormOnSuccess.js

  • Component Path: Rules/Forms/Notes/

  • Performs required post-processing after text has been added to the note property of an SAP business object initiated from a Mirata form.

3.3.4.8 NoteUpdateNewTextStringWithMirataNote.js

  • Component Path: Rules/Forms/Notes/

  • Obtains text from a Mirata form to be added to the SAP business object in context. Then, based on SSAM configuration settings, either appends the text to existing "new" note text (if any) that may have been added to the business object since the last synchronization session was performed, or uses the text to replace any existing "new" note text.

3.3.4.9 NoteUpdateTextStringWithMirataNote.js

  • Component Path: Rules/Forms/Notes/

  • Appends text from a Mirata form to the "remote" note text of the SAP business object in context (i.e.- the note text received during the previous synchronization session).

3.3.4.10 FormStart.js

  • Component Path: Rules/Forms/Workflow/

  • Adds text to the “notes” property (i.e.- “long text”) of the work order operation in context recording when the mobile user started a form. The note includes the date, time, and SAP username of the user.

  • Designed to be called from a Mirata from transition using an Integration Action of type Embedded Integration Event.

3.3.4.11 FormWorkComplete.js

  • Component Path: Rules/Forms/Workflow/

  • Adds text to the “notes” property (i.e.- “long text”) of the work order operation in context recording when the mobile user completed a form. The note includes the date, time, and SAP username of the user.

  • The page displaying the Mirata form is closed after the note text is added.

  • Designed to be called from a Mirata from transition using an Integration Action of type Embedded Integration Event.

3.3.4.12 ReturnWorkOrderOperationsArray.js

  • Component Path: Rules/WorkOrders/

  • Provides an example of a rule that returns an array of objects that can be called by a Mirata Integration Data Mapping definition to populate an array-type field in a Mirata form that has an array row definition composed of multiple form fields.

3.3.4.13 EnableMirataToolbarIcon.js

  • Component Path: Rules/WorkOrders/Operations/

  • Determines if the Mirata toolbar icon should be enabled based on the current SSAM assignment type, the status of the current work order/operation and if it is form-enabled.

3.3.4.14 EnableWorkOrderOperationEdit.js

  • Component Path: Rules/WorkOrders/Operations/

  • Overrides the default SSAM enable/disable logic for the "Edit" (i.e.- pencil) toolbar icon displayed on the Work Order Details screen.

  • If the Mirata "M" toolbar icon is displayed, then hide the Edit icon. Otherwise, call the default SSAM enable/disable function for the "Edit" toolbar icon.

3.3.4.15 GetOperationEquipmentDescription.js

  • Component Path: Rules/WorkOrders/Operations/

  • Retrieves the description of the equipment associated with an operation.

  • The context parameter passed is assumed to be bound to the target work order operation.

  • Designed to be called by a Mirata Integration Data Mapping definition.

3.3.4.16 GetOperationFuncLocDescription.js

  • Component Path: Rules/WorkOrders/Operations/

  • Retrieves the description of a functional location associated with an operation.

  • The context parameter passed is assumed to be bound to the target work order operation.

  • Designed to be called by a Mirata Integration Data Mapping definition.

3.3.4.17 GetOperationFuncLocId.js

  • Component Path: Rules/WorkOrders/Operations/

  • Retrieves the (human readable) ID of the functional location associated with an operation.

  • The context parameter passed is assumed to be bound to the target work order operation.

  • Designed to be called by a Mirata Integration Data Mapping definition.

3.3.4.18 GetWorkOrderEquipmentDescription.js

  • Component Path: Rules/WorkOrders/Operations/

  • Retrieves the description of the equipment associated with the parent work order of an operation.

  • The context parameter passed is assumed to be bound to the target work order operation.

  • Designed to be called by a Mirata Integration Data Mapping definition.

3.3.4.19 GetWorkOrderFuncLocDescription.js

  • Component Path: Rules/WorkOrders/Operations/

  • Retrieves the description of the functional location associated with the parent work order of an operation.

  • The context parameter passed is assumed to be bound to the target work order operation.

  • Designed to be called by a Mirata Integration Data Mapping definition.

3.3.4.20 GetWorkOrderFuncLocId.js

  • Component Path: Rules/WorkOrders/Operations/

  • Retrieves the (human readable) ID of the functional location associated with the parent work order of an operation.

  • The context parameter passed is assumed to be bound to the target work order operation.

  • Designed to be called by a Mirata Integration Data Mapping definition.

4) Mirata Form Definition Compatibility

Specific Mirata Form definitions are required to allow the Mirata Integration Metadata Component to manage Mirata forms embedded in the SSAM MDK application.

4.1 Integration Data Mappings

Integration Data Mapping definitions allow a Mirata form embedded in SSAM to obtain data from the SSAM application.

Two Integration Data Mapping definitions are required. Note that the “Name” attributes used below are only suggestions and can be any valid name.

4.1.1 Work Order ID

Obtains the number (or “ID”) of the work order currently in context from the SSAM application.

  • Name: Work Order ID

  • Integration: MDK

  • Value Type: String

  • Definition:
    {

    “integration-data”: “{OrderId}”,

    “type”: “string”

    }

4.1.2 Operation ID

Obtains the number (or “ID”) of the operation currently in context from the SSAM application.

  • Name: Operation ID

  • Integration: MDK

  • Value Type: String

  • Definition:
    {

    “integration-data”: “{OperationNo}”,

    “type”: “string”

    }

4.2 Form Fields

Each embedded form definition requires three form fields to be defined using the Mirata Designer. Note that the “Name” attribute for each field must be defined exactly as shown below and in all lower case. These fields should be defined outside of any “group” container field, as follows:

4.2.1 mobile-complete

This form field is used to record when the Mirata form has been completed by the SSAM mobile application user. Note that this “completion event” does not necessarily imply that the Mirata form’s workflow has been completed. Rather, it only reflects that the portion of the workflow that is the responsibility of the SSAM mobile application user has been completed.

  • Name: mobile-complete

  • Type: boolean

  • Initial value: false

4.2.2 work-order-id

This form field is used to record the work order number that was in context in the SSAM application when the Mirata form was first presented.

  • Name: work-order-id

  • Type: string

  • Initial value: calculation

    • Term: integration-data

Parameter: <Work Order ID Integration Data Mapping> (see 4.1.1)

4.2.3 operation-id

This form field is used to record the operation number that was in context in the SSAM application when the Mirata form was first presented.

  • Name: operation-id

  • Type: string

  • Initial value: calculation

    • Term: integration-data

    • Parameter: <Operation ID Integration Data Mapping> (see 4.1.2)

4.3 Header Fields

Each embedded form definition requires two form “header fields” to be defined using the Mirata Designer (see Figure 3). These header field definitions allow a form submission to be associated with the specific work order and operation that were in context in the SSAM application when the Mirata form was first presented.

4.3.1 work-order-id

  • Referenced field: work-order-id

  • Label: <user defined value>

4.3.2 operation-id

  • Referenced field: operation-id

  • Label: <user defined value>

4.4 Workflow Transitions

4.4.1 'Complete" Transition

Each embedded form requires a workflow transition to be used by the SSAM mobile user to “complete” the form. Note that executing this workflow transition does not necessarily imply that the Mirata form’s workflow has been completed. Rather, it only reflects that the portion of the workflow that is the responsibility of the SSAM mobile application user has been completed.

The “complete” transition must perform the following actions…

  • Present a transition button that the user can press to “complete” the form.

  • Set the mobile-complete form field to (boolean) true.

  • Execute an “Integration Action” of type “Embedded Integration Event” that closes the current application page that is displaying the Mirata form.

The following actions may also be considered for the “complete” workflow transition:

  • Assign the form to a different user or group to be reviewed and/or approved.

  • Present an “Are you sure?” confirmation dialog window to the user.

4.4.2 Integration Actions

The Mirata Integration Metadata Component provides two MDK rule definitions that can be used by Integration Actions of type Embedded Integration Event which may be useful to reference in the workflow definition of embedded forms.

4.4.3 FormStart.js

This MDK rule adds text to the “notes” property (i.e.- “long text”) of the work order operation in context recording when the mobile user started a form. The note includes the date, time, and SAP username of the user. See section 3.3.4.10 for rule details.

Using the Mirata Admin Tool, this rule can be referenced in by an Integration Action of type Embedded Integration Event using the following request definition:

{

  “key”: “ruie”,

  “value”: "/MirataFormsIntegrationComponents/Rules/Forms/Workflow/FormStart.js"

}

Once defined, this Integration Action may be considered for inclusion in the “create” workflow transition of each embedded form.

4.4.4 FormComplete.js

This MDK rule adds text to the “notes” property (i.e.- “long text”) of the work order operation in context recording when the mobile user completed a form. The note includes the date, time, and SAP username of the user. The page displaying the Mirata form is then closed after the note text is added. See section 3.3.4.11 for rule details. 

Using the Mirata Admin Tool, this rule can be referenced in by an Integration Action of type Embedded Integration Event using the following request definition:

{

  “key”: “ruie”,

  “value”: "/MirataFormsIntegrationComponents/Rules/Forms/Workflow/FormComplete.js"

}

Once defined, this Integration Action may be considered for inclusion in the “complete” workflow transition of each embedded form.

5) Appendix A: Acronyms, Abbreviations & Definitions

Term

Meaning

API

[Provide definition of the term used in this document.]

CIM

Component Integration Metadata

A CIM file is a configuration file used to integrate a custom metadata component and/or custom branding information into an existing MDK application.

MDK

Mobile Development Kit

A software application platform provided by SAP for building and deploying mobile applications that run on multiple mobile platforms

OData

Open Data Protocol

A protocol that allows the creation and consumption of queryable and interoperable REST APIs in a simple and standard way.

SSAM

SAP Service and Asset Manager

A client-server-based application utilizing a mobile application client that is used for enterprise asset and work management

UI

User Interface

Enables a human to interact with a computer or “smart” mobile device such as a tablet or mobile phone. It is typically composed of a series of pages, screens, buttons, forms, and other visual elements that allows a human to interact with the device.