Page Comparison

With embedded forms you can display emakin forms in other applications in HTML iframe.Embedded form layout can be accessed from "http(s)://<mydomain>, 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.
  

  Image Added

• 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:

https://mydomain.emakin.com/app

...

Image Removed

Authentication

Embedded forms needs valid authentication, if user is not logged in before, browser automatically redirected to login page. Alternatively you can specify an authentication token to login user automatically and skip login page.

Example embedded page url with authentication token;

	http://ertan/?/initiate/55....6b/c2...18/08...c8&apiKey=58ea0f3d.....90b984be905a 

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.

  Image Added

• 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:

https://mydomain.emakin.com/app/embed.aspx?/workitem/d4c1adc7-c9d2-4af0-a2b3-b6d61d88df6d&auth=41AA3CE3CAFBreport/55....c8&apiKey=58ea0f3d..........BF8114

You can generate required authentication token with getToken method in rest service. 

Generated authentication tokens are limited to configured based time period and they can be expire. Please always generate new tokens as long as needed and do not store in any place like disk or code.

Embedding Form

...

90b984be905a

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:

https://mydomain.emakin.com/app/?/report/55....c8&auth=41A....114

Embedding a Form

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

Example:

<html>
	<body>
       
Hello!
		<iframe src="httphttps://ertanmydomain.emakin.com/app/embed.aspx?/workitem/d4c1adc7-c9d2-4af0-a2b3-b6d61d88df6dinitiate/55..c8&apiKey=58ea0f3d.....90b984be905a" width="100%" height="600300" frameborder="0"></iframe>
	</body>
</html>

Default configuration is prevents the use emakin in IFrame tag because of security. If you get any error please try to remove "X-XFrame-Options" header from your web configuration file to allow to use emakin in iframe tag.

Action Toolbar

...

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:

<html>
	<body>

       Hello!
		<iframe src="httphttps://ertanmydomain.emakin.com/app/embed.aspx?/workitem/d4c1adc7-c9d2-4af0-a2b3-b6d61d88df6d&actions=1initiate/55..c8&apiKey=58ea0f3d.....90b984be905a&returnUrl=http://localhost" width="100%" height="600300" frameborder="0"></iframe>
	</body>
</html>

Return Address

You can specify "returnUrl" parameter in query string to redirect user another address after form is completed. This parameter is only meaningful if action toolbar is visible.

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.

<html>
<body>
<iframe id="frame" src="https://mydomain.emakin.com/app/embed.aspx?/workitem/d4c1adc7-c9d2-4af0-a2b3-b6d61d88df6d&actions=1initiate/55..c8&apiKey=58ea0f3d.....90b984be905a&returnUrl=http://localhost" width="100%" height="600300" frameborder="0"></iframe>
	</body>
</html>

...

<script src="https://static.emakin.com/r/IFrameResizer/JS?c=en-US"></script>
<script>iFrameResize({ minHeight:300 }, '#frame')</script>
</body>

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:

<iframe src="https://mydomain.emakin.com/app/?/initiate/55..c8&apiKey=58ea0f3d.....90b984be905a&CompanyId=123e4567-e89b-12d3-a456-426614174000" width="100%" height="600px"></iframe>

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).

<iframe src="https://mydomain.emakin.com/app/?/initiate/55..c8&apiKey=58ea0f3d.....90b984be905a&culture=en-US" width="100%" height="600px"></iframe>

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