Versions Compared

Old Version 3

changes.mady.by.user Ertan Tike

Saved on

compared with

New Version Current

changes.mady.by.user Selahattin Bostanci

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

With embedded forms you can display emakin forms in other applications in HTML iframe.

Embedded form layout can be accessed from "http(s)://<mydomain>.emakin.com/app/embed.asmx" url.

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;

...

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

Info

Test Mode

Please note that anonymous access is only available for processes in an "Active" state. If you attempt to use anonymous access while a process is in "Test" mode, Emakin will silently ignore the operation, ensuring that test processes are not unintentionally exposed.

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:

Code Block
languagehtml
https://mydomain.emakin.com/app/?/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:

Code Block
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

You can embed emakin forms in a basic HTML IFrame tag like below;

Example:

Code Block
<html>
	<body>
        Hello!
		<iframe src="http://ertan90b984be905a

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:

Code Block
languagehtml
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:

Code Block
languagehtml
<html>
<body>
Hello!
<iframe src="https://mydomain.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:

Code Block
languagehtml
<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.

Code Block
languagehtml
<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>
Note

Unlike other examples, make sure to assign an ID to the IFrame element that you want to monitor, as this is essential for tracking and dynamically adjusting its size.

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:

Code Block
languagehtml
<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.

Info

As a best practice, we advise keeping the number of parameters passed through the URL to a minimum. Instead, consider submitting a single identifier (such as an Id parameter) and handling any additional data retrieval within the process’s prework section. For instance, by passing only an Id, you can use it within the prework to query necessary details, ensuring the process is streamlined and secure.

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

Code Block
languagehtml
<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.