Mirata DeepLink API Configuration

Overview

Mirata enables the configuration of deep linking from another website/mobile application to the respective web or mobile inbox. From a conventional perspective, any deep linking from an external application to a Mirata Inbox is referred to as the Mirata Deep Link API (DLAPI) configuration. The configuration process is the same regardless of the external application source (i.e. web vs. mobile).

Additionally, Mirata enables deep linking configuration from a Mirata Form in the web or mobile inbox to an external website/mobile application. This is covered in another article: Mirata DeepLink to External Application.

Differences Between DLAPI and Standard Links

The DLAPI configuration allows the Web Inbox to process a URL that can correctly generate a form definition or search for a form definition. This is different from a standard URL because the standard link structure doesn't have the logic to create or search for a form in the Inbox.

For the remainder of this document, a fake company called “acme” will be used to illustrate how the DLAPI configuration should look. Additionally, an external application, Postman, was used to capture certain screenshots specifically for this documentation. It is important to note that when configuring deep links, Postman will not be used anywhere.

DLAPI Prerequisites

For the Deep Link process to function as expected there are certain requirements and configuration that must be in place.

Web-Based Configuration Prerequisites

For web-based DLAPI configuration, any user who will be accessing the Mirata Inbox application from an external application, must have the appropriate user permissions created in the Mirata Admin tool. If a user(s) does not have a reciprocal user account created within the Mirata Admin tool, they will not be able to create or use any forms in the Mirata Inbox.

Mobile-Based Configuration Prerequisites

It is important to note that the web-based configuration prerequisites also apply for mobile-based configurations. In addition to having the proper user permissions in place, any user who will be accessing a Mirata Inbox mobile application, must have the application downloaded on the same device the deep link is being launched from.

DLAPI Configuration Details

There are three components that comprise the DLAPI configurations which are as follows:

HTTP Request Type

The HTTP request type is only important if for some reason the deep link is being executed via some kind of service that does not allow for the deep link to be made directly available to a user. In the scenario in which the an HTTP request must be processed, the request type is HTTP GET.

The reason this is being mentioned is because if you are using another application/tool to test the Mirata DLAPI configuration, you must set the request type as GET.

View image

Above screenshot from Postman

Base URL

The Base URL is the component of the DLAPI configuration that will remain the same for all forms within a single environment. The specifics about which form is part of the DLAPI will come in the next section which discusses the encoded payload.

Suppose for our fake client acme we had the following Base URL for the "dev" environment:

https://dev.acme.mirataforms.com/inbox/index.html#/dlapi/{{encodedpayload}}

If this link needed to be applied to the "qa" environment, the link would look like the following:

https://qa.acme.mirataforms.com/inbox/index.html#/dlapi/{{encodedpayload}}

And if the link needed to be applied to the "prod" environment, the link would look like the following:

https://prod.acme.mirataforms.com/inbox/index.html#/dlapi/{{encodedpayload}}

To genericize this further, if this needs to be applied for a specific environment, the two things that need to be set are the environment and the client name within the URL as follows:

https://[environment].[client].mirataforms.com/inbox/index.html#/dlapi/{{encodedpayload}}

Encoded Payload

The Encoded Payload is the portion of the DLAPI that specifies what actions to take when the URL is launched from the external application.

Example: Creating a Specific Form

Suppose, the purpose of the URL was to only create a new form with the form-id: "acme-dev.form.sample-form" the following encoded payload would need to be in place:

const payload = 
{
    "create": {
        "definitionId": "acme-dev.form.sample-form",
        "transition": "create",
    }
};
 
const encoded = encodeURIComponent(JSON.stringify(payload));
pm.environment.set("encodedpayload", encoded);

As indicated by the body of the encoded payload above, the form will launch to the "create" transition, which is the transition that is used to create any Mirata form. This will be important for later.

There are two things within the payload that need to be covered here before proceeding:

Putting everything together Base URL + Encoded Payload, a URL is generated that looks like the following:

https://dev.acme.mirataforms.com/inbox/index.html#/dlapi/%7B%22create%22%3A%7B%22definitionId%22%3A%22acme-dev.form.sample-form%22%2C%22transition%22%3A%22create%22%7D%7D

The link above is something that can be pasted into a browser window and interpreted to execute in the Mirata Inbox.

Example: Creating a Specific Form and Passing Values

Suppose now, instead of just creating the form, specific data values needed to be passed to the create transition. For sample purposes, there are 2 fields in the create transitions: OrderId and OperationNum.

This can be accomplished by adding the "data" object to the Encoded Payload:

const payload = 
{
    "create": {
        "definitionId": "acme-dev.form.sample-form",
        "transition": "create",
        "data": {
            "OrderId": "TD2000050",
            "OperationNum": "0040",
        }
    }
};
 
const encoded = encodeURIComponent(JSON.stringify(payload));
pm.environment.set("encodedpayload", encoded);

The most important thing to note here is that the fields within the "data" object match the name of the fields within the create transition dialog. If this is not the case, the data will not be appended to the fields properly.

With this addition in place, the URL will look like the following:

https://dev.acme.mirataforms.com/inbox/index.html#/dlapi/%7B%22create%22%3A%7B%22definitionId%22%3A%22acme-dev.form.sample-form%22%2C%22transition%22%3A%22create%22%2C%22data%22%3A%7B%22OrderId%22%3A%22TD2000050%22%2C%22OperationNum%22%3A%220040%22%7D%7D%7D

Example: Searching For a Form With Specific Values/Creating a Specific Form and Passing Values

Often times, it is important to check if a specific form already exists for the data that is being passed via the URL. In this case, the goal is to not create a duplicate form for the same data from the external system. Mirata offers the ability to search for an existing form definition that contains data within the DLAPI Encoded Payload configuration:

const payload = 
{
  "search": {
    "filter": {
        "definitionId": "acme-dev.form.sample-form",
        "headerInfo": {
            "OrderId": "TD2000050",
            "OperationNum": "0040"
        }
    },
    "create": {
        "definitionId": "acme-dev.form.sample-form",
        "transition": "create",
        "data": {
            "OrderId": "TD2000050",
            "OperationNum": "0040",
        }
    }
  }
};
 
const encoded = encodeURIComponent(JSON.stringify(payload));
pm.environment.set("encodedpayload", encoded);

The most important thing to know when incorporating the "search" function into the Encoded Payload is the "headerInfo" object. What this means is that the fields that are being searched for must be header (search) fields on the form. This is configured on the form in the designer. Please see the Search Fields (Header Fields) article for more information.

It is also important to note that the "create" function is also inside the "search" function.

With the search in place within the Encoded Payload, the URL will look something like the following:

https://dev.acme.mirataforms.com/inbox/index.html#/dlapi/%7B%22search%22%3A%7B%22filter%22%3A%7B%22definitionId%22%3A%22acme-dev.form.sample-form%22%2C%22headerInfo%22%3A%7B%22OrderId%22%3A%22TD2000050%22%2C%22OperationNum%22%3A%220040%22%7D%7D%2C%22create%22%3A%7B%22definitionId%22%3A%22acme-dev.form.sample-form%22%2C%22transition%22%3A%22create%22%2C%22data%22%3A%7B%22OrderId%22%3A%22TD2000050%22%2C%22OperationNum%22%3A%220040%22%7D%7D%7D%7D

Data for DLAPI URL

The DLAPI is often generated from an external system (ex: SAP). Since the external systems are not owned or controlled by Mirata, the external systems must place the correct data within the DLAPI request, whether that be for a create only or a create and search URL.

That means that the URL that is generated can be reused and the required data fields can be populated with whatever mechanism the external system uses to replace input parameters with actual data values.