Building Forms Embedded in SAP Asset Manager (SAM)

Building Forms Embedded in SAP Asset Manager (SAM)


How do Mirata forms work embedded in SAP Asset Manager (SAM)?

Mirata forms can be embedded on any standard or customer SAP object. You do not need to be a SAM expert to build a Mirata form that can be used embedded in SAM.


Add header fields in the Designer to tie the form to the object in SAP that you want SAM users to launch the form from (step 2 below). When a SAM user navigates to an object that’s configured to use Mirata forms (in this case, the Work Order Operation), they’ll see the Mirata “M” in the top right corner. Clicking the Mirata "M" will seamlessly initiate the Mirata form associated with the corresponding Work Order Operation (step 5 below). Subsequently, the SAM user can use the Mirata form just like they would in the Mirata Inbox.


SAM users need a SAP user set up in Mirata in order to use SAM embedded Mirata forms (step 6 below). This means if you have access to both forms embedded in SAM and forms in the Mirata Inbox, you will have two separate users in Mirata. Access to Mirata forms in SAM follows the same permission rules as access to Mirata forms in the Mirata Inbox. The SAM user’s access to a particular work order does not mean they have access to the associated form - form permissions are still configured in the Mirata Admin Tool. 


When the SAM user returns to SAM from the Mirata form and syncs SAM with an internet connection, the data that was collected in the form will be synced with the Mirata server. You might want to configure your form to, at this point, assign to an approver who will open the same Mirata form submission in the web Inbox.


In the Designer, you have two tools that you’ll use for every SAM form:

  1. Pull data from SAM into your form using Integration Data Mappings in any form field calculation (step 3 below). 
  2. Add MDK “Embedded Integration Event” Integration Actions to fire MDK rules during workflow transitions (step 4 below). MDK rules are the mechanism for your Mirata form to communicate to SAM things like: create a new form submission, save form data, close the form and return back to SAM, etc.


Overview of steps to embed a Mirata form in SAM 

  1. SAP Administrator: Create a Connection to SAP (one-time setup) in the Admin Tool
  2. Non-Technical Form Builder: Set up header fields on your form in the Designer
  3. Non-Technical Form Builder: Use Integration Data Mappings in your form/workflow in the Designer 
  4. Non-Technical Form Builder: Add Integration Action(s) to your workflow in the Designer
  5. Non-Technical Form Builder / SAP User: Configure SAP to tie the Mirata form to the corresponding records in SAP
  6. Non-Technical Form Builder / System Administrator: Make sure SAM users have SAP users in Mirata and have access to your form in the Admin Tool


(1) Create a Connection to SAP (one-time setup) in the Admin Tool

You need a Connection to SAP created in Mirata for forms to work embedded in SAM. This only needs to be set up once and should be done by a System Administrator.


To create a Connection or see if there’s already a SAP Connection set up, go to the ADMIN tab in the Admin Tool and then go to the Connection Info tab on the left. If you’re a System Administrator, go to the Create a Connection section of the How to Integrate with Other Systems article for details on setting up a new Connection in Mirata


(2) Set up header fields on your form in the Designer

NOTE: The fields you need to add as header fields in this step is dependent on which SAP object you want to launch this Mirata form from in SAM. In this example, the form will be launched from a Work Order Operation. If you want to launch this Mirata form from a different SAP object, contact your SAP Admin to understand which header fields to include. 


Open the form you want to use in SAM in the Mirata Designer. Go to the Designer Overview article if you’re unfamiliar with the Designer


Add two “Text Input” components to your form. Make sure these fields are not within any sections or groups. These inputs will be for the Work Order ID and the Operation ID. You should name them: “WorkOrderId” and “OperationId” respectively. 


At the bottom of the Form Details tab of the left panel, you’ll add two fields in “HEADER INFO” using the “+ Add Field” button. Map one to the “WorkOrderId” field and one to the “OperationId” field.

You can hide these fields on your form by setting visible to false in the Presentation Properties.


(3) Use Integration Data Mappings in your form/workflow in the Designer

Integration Data Mappings are a way to bring data from SAM into your Mirata form. For example, you may want the Mirata form to pull in the Equipment data from the Operation that the SAM user is working on. 


You can use Integration Data Mappings as much as you need to in your form/workflow, but you’re only required to configure two mappings (for the WorkOrderId and OperationId fields we created in step 2) so that a form works embedded in SAM (see below).


Integration Data Mappings are set up in the Admin Tool. Your Mirata environment will come with the standard MDK Integration Data Mappings already preloaded. If you don’t see a mapping that you need, contact your SAP Administrator to get it added.


You’ll use Integration Data Mappings in the Calculation Editor in the Designer. Simply use the “integration-data” calculation to bring in data from SAM (through MDK). The “integration-data” has two pieces:

  1. Name: When you click the arrow in the name, you’ll get a selection window to select one of the Integration Data Mappings that’s set up in your Admin Tool. You can search by Name, Description, Integration Type, or Group to find the mapping you’re looking for.
  2. Default: The default value will be used in lieu of the Integration Data Mapping from SAM when you’re using the form outside of the SAM app (in a web browser or Mirata mobile app).


Integration Data Mappings for Header Fields

For the header fields you created in step 2, use the “integration-data” calculation for their initial value to map them to the “Work Order ID” and “Operation ID” standard MDK Integration Data Mappings. Your calculations should look like this:

If your SAP Admin instructed you to use other header fields, map those to their corresponding standard SAP mapping.


(4) Add MDK Integration Actions to your workflow in the Designer

Like MDK Integration Data Mappings, your Mirata environment will come preloaded with the standard MDK Integration Actions, so you don’t have to worry about setting up these actions unless you’re trying to do a custom action as a SAP Admin. 


Add MDK Integration Actions to your workflow in the Designer just like you add any other type of Integration Action. There are no inputs to MDK Integration Actions. Go to the Edit Mode Layout section of the Workflow Designer Overview article to find where to add Integration Actions to your workflow transitions


There are a few MDK Integration Actions that we recommend utilizing for every Mirata form you’re going to embed in SAM:

  1. Create Transition: For your create transition, add the “MDK Form Start” integration action to this transition. 
  1. Save Transition: We recommend creating a save transition that simply saves your form. Add the “MDK Form Save” integration action to this transition.
  1. Back Transition: If you click the back arrow in the top left of the Mirata form in SAM, you will lose any unsaved changes. Because of this, we recommend creating a transition for users to save their form when returning back to SAM (in the below screenshot, this is “Asset Manager”). Add the “MDK Form Save and Return” integration action to this transition to save the form and navigate the user back to the SAM app. 
  1. Complete Transition: Create a transition for your users to use when they’re done filling out the Mirata form. You likely will want to assign the form to an approver group in this transition, so that someone can approve the form in the web inbox. Add the “MDK Form Complete” integration action to this transition to save the form and navigate the user back to the SAM app.

(5) Configure SAP to tie the Mirata form to the corresponding records in SAP

Talk to your SAP Administrator about how they’ve configured your SAP to link Mirata forms to objects in SAP. Most customers will do this through a custom field on the SAP object which holds the Mirata Form ID. 


To get the Mirata Form ID, go to the Form Catalog in the Admin Tool and go to the details page for the form. There, you’ll be able to copy the Mirata Form ID.


(6) Make sure SAM users have SAP users in Mirata and have access to your form in the Admin Tool

SAM users need a SAP user set up in Mirata in order to use SAM embedded Mirata forms. This means if you have access to both forms embedded in SAM and forms in the Mirata Inbox, you will have two separate users in Mirata. For example below, looking at the Provider column, this user has a COGNITO user and a SAP user. The email address used for the Mirata SAP user must be the same as the email address used for their SAP account.


Access to Mirata forms in SAM follows the same permission rules as access to Mirata forms in the Mirata Inbox. The SAM user’s access to a particular work order, or other SAP object, does not mean they have access to the associated form - form permissions are still configured in the Mirata Admin Tool. 


When logging into Mirata, on the left-hand side, you’ll see options to log in through any SAP Providers that are set up for your organization. In this example below, there are two SAP Providers configured that I can log in through. If you want to make sure that a SAP user has access to a form you created, then have that user log into the Inbox through their SAP connection and make sure they see that form in the create form dialog. When you log into the Inbox as a SAP user, the forms you see available in the create form dialog align with those that will function for the same SAP user within SAM.



Troubleshooting: I followed the steps above, but my form isn’t loading when the Mirata “M” is clicked in SAM


Some common mishaps to double check are: 

  1. Make sure you added the Integration Data Mappings in step 3.
  1. Make sure you added the MDK Form Start action to your create transition in step 4.
  1. Make sure there are no issues with your form/workflow definition. In the Admin Tool Form Catalog, if you navigate to the form’s details page by selecting the form then clicking the pencil button, you’ll see a red error message if the definition is invalid. Make sure to refresh your browser to get the latest results. 
  1. Make sure the SAM user has a SAP user created in Mirata with the same email address as their SAP login. See step 6 above.
  1. Make sure the SAM user has access to the Mirata form by configuring their role rights in the Admin Tool. If the SAM user does not have access, then the form will not load for them in SAM. See step 6 above.