Embedding Emakin

With embedded forms, you can easily integrate Emakin forms into other applications using an HTML <iframe>. Emakin’s responsive design ensures that the form automatically adjusts to fit the frame size, providing a smooth and consistent user experience across different devices and screen sizes.

To access embedded forms, you can choose between a valid authentication method or allow anonymous access, depending on your security requirements.

Anonymous Access

Anonymous access allows users to interact with forms or generate reports in other applications without needing to log in to Emakin. This can be achieved by using API Keys, providing a seamless and frictionless experience for users who do not require authentication.

Initiating a New Process Anonymously

To enable anonymous access for initiating a new process, follow these steps:

• Enable Anonymous Access: Ensure that anonymous access is enabled for the process you want to initiate or share. This setting allows the process to be accessed without requiring user authentication.
  
  

  Open

  

  Anonymous

• Generate an API Key: Create an API Key with the "login" scope and any other necessary scopes. Be cautious and select only the mandatory scopes, as allowing anonymous access can increase the risk to your system.

• Update the Process Link: Copy the initiation link of the process. Replace the # character in the URL with ?, then append the generated API Key as a parameter at the end of the address.

The updated URL should look similar to the following example, with the "apiKey" parameter added:

Sharing a Screen with Anonymous Access

To share a screen view anonymously, follow these steps:

• Enable Anonymous Access: First, ensure that anonymous access is enabled for the screen you wish to share. This setting allows users to view the screen without needing to log in.

  Open

  

• Generate an API Key: Create an API Key with the "login" scope and any other required scopes. It’s important to only select the necessary scopes, as granting anonymous access can increase the system’s vulnerability.

• Update the Screen Link: Copy the screen's URL. Replace the # character in the address with ?, then append the generated API Key as a parameter at the end of the URL.

The updated URL should look similar to the following example, with the "apiKey" parameter included:

Authenticated Access

To secure access, you can generate authentication tokens using the GetToken method from the REST API service for a specific user identity. Once the token is generated, include it as an "auth" parameter in the URL.

Please note that these authentication tokens are valid only for a configured time period and will expire after that. It is essential to generate new tokens whenever needed, and ensure that they are not stored on disk or hardcoded in your application.

The updated URL with the "auth" parameter should look similar to the following example:

Embedding a Form

You can easily embed Emakin forms using a basic HTML <iframe> tag, as shown in the example below:

Example:

Return Address

You can specify a returnUrl parameter in the query string to redirect the user to another address after they have completed the form.

Example:

IFrame Size

For some forms, the height of the interface may change dynamically. If you want the IFrame size to adjust automatically according to the form's content, you can use an additional JavaScript library to apply these size changes dynamically.

Sending Parameters

When embedding Emakin forms, you may need to submit additional values to the Emakin form data. Emakin supports receiving parameters through query strings, allowing you to set values directly within the process instance.

How to Submit Parameters

To specify a parameter, add it to the embedding URL using the following format:

• Query String: Use ?parameterName=value to pass parameters as part of the URL.

Note: For nested nodes, you can specify the exact path using path segmentation. Structure the parameter name as nodeName/nestedNode/nestedNestedNode to target a specific field within the hierarchy.

Example

Suppose you want to submit a CompanyId parameter, represented as a GUID. This can be done by appending the parameter to the URL:

In this example, the CompanyId parameter is assigned a unique identifier (GUID), which will be used in the process instance upon load.

Sending the Culture Parameter

When embedding forms, you may sometimes need them to display in a specific culture or locale, which determines the language, date formats, and other region-specific settings. This can be particularly useful in applications serving a global audience or in situations where the user’s culture is known and you want to provide a seamless experience.

How to Send the Culture Parameter

To specify a culture when embedding a form, you can include the culture parameter in the embedding URL. The culture parameter should be a valid IETF language tag, such as en-US for English (United States) or fr-FR for French (France).

In this example, the form will be displayed in the English (United States) culture.