You can set up Mirata forms to securely exchange data with other systems by following the steps detailed in this article. The initial two steps in the Admin Tool should be handled by someone with an understanding of your system's network APIs and security. Following that, non-technical form builders can seamlessly incorporate the integrations at the preferred points within their forms and workflows in the Designer.

While examples used in this article are for integrating with SAP, these steps are for integrating Mirata with any outside system.

Overview of steps to integrate with another system (each step detailed below)

1. System Administrator: Create a Connection in the Admin Tool (one-time setup for each outside system)
2. Techno-Functional Resource: Create Backend Action(s) in the Admin Tool
3. Non-Technical Form Builder: Select the Backend Actions at the desired steps in your Form/Workflow in the Designer 

1. To send data from another system to Mirata
2. To pull data into a Mirata form from another system

(1) Create a Connection (one-time setup)

For each system you want to integrate with, you’ll need to create a Connection. This only needs to be set up once per API and should be done by a System Administrator.

To create a Connection, go to the ADMIN tab in the Admin Tool and then go to the Connection Info tab on the left. Go to the Admin Tool Overview article for an overview of the Admin Tool

Provide the below information to create a Connection:

(*) Indicates required information

Now that you have your Connection set up, you’ll create an Backend Backend Action to communicate with the API that pulls data in from or sends data to another system.

(2) Create an Backend Action

To pull in data from or send data to another system, you will use Backend Actions.  Backend Actions are a versatile way of creating network requests to interact with other systems. They can be used by the form designer to facility updates to/from the form, without needing to know the technical details of the integration system. To set up your integration, use an Backend Action with the type "HTTP Request".

To create an Backend Action, go to the ADMIN tab in the Admin Tool and then go to the Backend Action tab on the left. Go to the “Backend Actions” section of the Admin Tool Overview article for more details about Backend Actions

Provide the below information to create the Http Request Backend Action. If you’re unsure about any of the below details, please contact your System Administrator for the system you’re trying to integrate with.

(*) Indicates required information

Using Input Parameters: You can use Input Parameters in the HTTP Request Body and Url Path fields. To use them, wrap the Input Parameter's name in curly brackets. For example, use the Input Parameter "FirstName" in the request body as follows: "Hello {FirstName}...".

NOTE: The Input Parameters you create will be data that can be mapped directly to input fields on the form/workflow by your form builders. Make sure to use user-friendly names for Input Parameters so it’s easy for form builders to figure out what data to provide.

After you’ve set up your Http Request, you can go to the TEST tab in the top right of the Backend Action page to test the call from Mirata. If you set up any Input Parameters, you’ll see them here so you can provide values. After the test is run, you’ll see success or error messages as well as the API response, if available. 

After you’ve tested your Backend Action and see the proper API response in Mirata, your Form Builders are now ready to use this Action in any of their forms.

(3a) Send data to another system from Mirata

In the Workflow Designer, you can add Backend Actions to transitions. When the Form User clicks to run a transition, the Actions associated with the transition will run. Go to the Workflow Designer Overview article for an overview of the Workflow Designer and transitions

Example: Send an image attachment to a SAP Work Order

In this example, we are sending an image attachment to an SAP Work Order whenever the form is approved by a supervisor. This is the Backend Action request in the Admin Tool:

Here are the steps you need to perform in the Designer: 

To add an Backend Action to a transition, (1) go to the BACKEND ACTIONS tab and then (2) click the + button. Make sure you have the right (3) transition selected on the bottom (the Approve transition in this example).

This dialog will appear and you should:

1. Name: Select the Backend Action you want to add to this transition. You can use the search bar in the top right to search by Action Name, Id, or Connection. 
2. For Each In Array: Optionally, you can run the action for each row in an array on your form or transition dialog by selecting the array. If you leave this blank, then the Action will run just once when the transition runs.
3. Filter: Optionally, you can configure a calculation for when the Action should run during this transition. If you leave this blank, then the Action will always run when this transition runs.
4. Input Data: If there are any Input Parameters set up for the Action you selected in step 1, then they will be listed in the Input Data section. You have two options to map in a value for each Input Parameter:

1. (1) Use the out arrow icon  to select a field from your form or transition dialog. When the transition runs, whatever value is in the selected field will be inserted as the value for the Input Parameter.
2. (2) Use the sigma icon to use a calculation to set the value for this Input Parameter. This can be anything from a very basic calculation to get the current time to a very complex calculation that references many fields.

After you click OK, you’ll see the Action listed in the BACKEND ACTIONS tab for the transition. 

That’s it! Now if you run this transition in the Inbox, your API to send data to another system will run. 

You can continue this process to add however many Actions as are needed.

(3b) Pull data into Mirata form from another system

You can pull data into an array (list, grid, or table) or dropdown field. 

Example: Display a list of SAP Work Orders and their metadata on your form

The end result for this example looks like this on the form:

This is the Backend Action request in the Admin Tool that returns the list of Work Order metadata based on a provided Partner Number:

And this is a sample of the response: 

Here are the steps you need to perform in the Designer: 

1. In the Designer, add an array field to your form.
2. For each field in the API response array that you want to bring into the form, add a field inside the array field on your form with the exact same name as in the API response. You can set the label of the field (what shows to the form user) to whatever you prefer for the form users.

1. For example, if your SAP API returns Work Order Number like below, then add a Text Input field inside of the array on your form and name it “AUFNR”. You could label it “Work Order Number” for the form users.
   
2. Additionally, if your SAP API returns Equipment Number and Equipment Description like below, then add another two Text input fields inside of the array on your form. Name one “EQUNR” and one “EQKTX”. You can label them “Equipment Number” and “Equipment Description” for the form users.
   

3. Select the entire array field and go to the Conditions tab . For initial, select query table and then select your Backend Action.
4. That’s it! Preview the form and see that the array field displays the Work Order Number, Equipment Number, and Equipment Description for the list of Work Orders received in the API response, like in the above screenshot.

Example: You want the form user to select a SAP Equipment Characteristic Value from the list of options available in SAP

The end result for this example looks like this on the form:

This is the Backend Action in the Admin Tool that returns the list of Equipment Characteristic Values from SAP:

And this is a sample of the response: 

Here are the steps you need to perform in the Designer: 

1. Drag a dropdown component onto your form.
   
2. For the dropdown field, in the Data tab  in the right panel, select Query Table as the Source Type and then provide the below information:
   

1. Query: Select the Backend Action.
2. Return: Enter the name of the field in the API response that you want to be the value returned into the field. In this example, you would enter “VALUE_CHAR” to use the Characteristic Values.
3. Sort By: Optionally, enter the name of the field in the API response that you want to sort the options in the dropdown by. In this example, you could also put “VALUE_CHAR” so they list in alphabetical order.
4. Sort Order: Select ascending or descending order.
5. Display: Select constant and then enter the name of the field that you want displayed as the options in the dropdown. In this example, you would enter “VALUE_CHAR” to use the Characteristic Values.
6. Parameters: If there are Input Parameters for the Backend Action you selected, map each input parameter directly to a field on the form or use a calculation to set the value.

3. That’s it! Preview the form and see that the options in the dropdown are coming from the API response.