Assembly Application Iframe Messages

As the planner, the assembly application can be embedded in a web site. This section describes Iframe messages that are listened by the assembly editor (input) to react to parent window actions or emitted by the assembly editor (output) to enable parent window to react.

 

For...	Inputs Messages	Outputs Messages
Authentication	Authentication TokenRefreshed	AuthenticationRequired, AuthenticationSucceeded, AuthenticationFailed, TokenExpired
Application	–	CloseApp
Open Save	LoadAssemblyFromProductId	OpenAssemblyRequired SaveSucceeded

Endpoints

A website offering access to the assembly editor application must embed it in an Iframe. The application endpoint to use depends on the integration context. You have to use your environment url, specifying assembly component followed by /Editor/ suffix.

Example: https://staging-assembly.xxx.by.me/Editor/

The xxx part depends on the integration context that was provided to you.

Iframe communication

To have an overview of the subject, we advise you to read window.postMessage documentation on the web.

➡️ Refer to PostMessage documentation 🔗

Every message received by the application or sent by the application through window.postMessage must be an object of this format:

Key	Type	Description
event	string	The event name is used as unique identifier for a given event.
content	*	Content sent with the event. It is optional and can be anything: integer, array, object...

Template

{
   event: "AuthenticationRequired",
   content: 
   {
      "token": string,
      "distributionID": string
   }
}

Authentication

AuthenticationRequired

Output emitted when the application requests authentication parameters. Upon this request, the parent window must reply with an Authentication message.

Key	Type	Value/Template	Description
event	string	AuthenticationRequired	–
content	–	–	–

Authentication

Input received when authentication is requested by the message AuthenticationRequired, the parent window must reply with the following message.

Key	Type	Value	Description
event	string	Authentication	–
content	object	token distributionID	token: The legal entity token generated by the client website. distributionID: The specific distribution in the legal entity.

Template

{
 "token": string
 "distributionID": string
}

AuthenticationSucceeded

Output emitted by the application to acknowledge that authentication is successful.

Key	Type	Value/Template	Description
event	string	AuthenticationSucceeded	–
content	object	origin appID distributionID distributionParams	origin: The domain from which the message originated. appID: The application ID associated with the provided credentials. distributionID: The distribution ID associated with the provided credentials. distributionParams: The distribution-specific parameters, if any, of the distribution associated with the provided credentials.

Template

{
    "origin": string,
    "appID": string,
    "distributionID": string,
    "distributionParams": object
}

AuthenticationFailed

Output emitted by the application to inform that authentication has failed.

Key	Type	Value/Template	Description
event	string	AuthenticationFailed	–
content	object	httpCode id message	httpCode: The HTTP error code for the request. id: The error id. message: The detailed error message.

Template

{
    "httpCode": HttpErrorCode,
    "id": string,
    "message": string
}

TokenExpired

Output emitted and sent to the parent window when a token is expired, subsequent calls to the web-services will fail with a 401 error.

Key	Type	Value/Template	Description
event	string	TokenExpired	–
content	–	–	–

TokenRefreshed

Input received from the parent window. This message is sent by the parent window on receiving TokenExpired. This message provides a new valid token to the application to authentify subsequent calls to web services.

Key	Type	Value	Description
event	string	TokenRefreshed	–
content	object	token distributionID	token: The legal entity token generated by the client website. distributionID: The specific distribution in the legal entity.

Template

{
 "token": string,
 "distributionID": string
}

Application

CloseApp

Output emitted when the user clicks on the cross button to close the application.

Key	Type	Value/Template	Description
event	string	CloseApp	–
content	–	–	–

Open Save

LoadAssemblyFromProductId

Input at reception of this message, the assembly application retrieves the product id in the platform and opens the assembly file (BMA) associated to it.

Key	Type	Value/Template	Description
event	string	LoadAssemblyFromProductId	–
content	object	id	id: Product on which to retrieve and open the assembly file.

Template

{
 "id": integer,
}

OpenAssemblyRequired

Output emitted when the user clicks on the open component button.

Key	Type	Value/Template	Description
event	string	OpenAssemblyRequired	–
content	object	productId	productId: The product ID of the component to open.

Template

{
    "productId": string,
}

SaveSucceeded

Output emitted when the assembly is saved sucessfully.

Key	Type	Value/Template	Description
event	string	SaveSucceeded	–
content	–	–	–