About Custom Forms

When you perform custom activities, you are redirected to the custom activity URL. In addition to the external URL, some additional information is sent as a post message that is a part of the HTML5 Web Messaging specification. The following data flow diagram describes the interaction between the Activities application and the custom form to establish the connection and send data.

The following procedure is described in the data flow diagram:

1. The user performs a custom activity in the Activities application.
2. The Activities application initiates the Handshake protocol by sending a message to the form and checks whether the URL of the custom form is valid.
   • If the URL is valid, the Activities application receives the message back. The application then adds an event listener to hear from the origin and then posts the message with the variable data to the custom form.
   • If the URL is not valid, an error message appears in the Activities application.

The window.postmessage() method is used to send data from the Activities application to the custom form. The window.postmessage() method enables cross-origin communication between the following items:

• Window objects such as between a page and a window that the page spawned.

  Example: The window.postmessage() method is used when you select the option to access the URL of the custom in a separate page.

• A page and iframe such as between a page and an iframe embedded within the page.

  Example: The window.postmessage() method is used when you select the option to access the URL of the custom form embedded within the window displaying the autolog sheet or as a replacement of the window displaying the autolog sheet.

The arguments (also called messages) passed to the window.postMessage() method are exposed to the receiving window through the event object. The Activities application creates an instance of target window to post message by using the following syntax:

targetWindow.postmessage(message, targetOrigin, [transfer]);

Where:

• targetWindow is a reference of the custom form window that receives the message.
• message is data to be sent to the custom form. The data is serialized using the structured clone algorithm. The algorithm enables you to pass a broad variety of data objects safely to the destination window without serializing them.
• targetOrigin is the origin of target window. By default, asterisk (*) is set to indicate no preference. The postMessage() transmits vital information. It is absolutely critical that this argument be a URI whose origin is the same as the intended receiver of the message containing the password to prevent interception of the password by a malicious third party.
• Transfer is a sequence of transferable objects that are transferred with the message. An optional parameter not used in the Activities application.

An event listener is added by the Activities application when the custom form is loaded to receive the message coming from the Activities application as shown in the following code snippet.

window.addEventListener(“message”, receiveMessage, false); 
function receiveMessage(event) 
{ 
    if (event.origin !== "http://example.org:8080") 
        return; 
        } 

The properties of the dispatched message are:

• data (event.data): The information passed by the Activities application.
• origin: The origin of the window that sent the message at the time postMessage was called. In the code snippet, the http://example.org:8080 is an example of origin.
• source: A reference to the window object that sent the message. You can use this property to establish two-way communication between two windows with different origins.

Remember the following security concerns when you use a custom activity:

• If you do not expect to receive messages from other sites, disable the Activities application to add any event listeners for message events.
• If you expect to receive messages from other sites, always verify the sender's identity using the origin and possibly source properties. Any window (including a URL) can send a message to any other window, and an unknown sender can send malicious messages. You must verify the syntax of the received message.
  Note: Failure to check the origin and possibly source properties enables cross-site scripting attacks.
• Always specify an exact target origin, not an asterisk (*) in the Activities application configuration when you use postMessage to send data to other windows. A malicious site can change the location of the window without your knowledge. Therefore, the site can intercept the data sent using postMessage.

{
                "loggedUserInfo": {
                    "token": <<token>>
                },
                "header": {
                    "activityId": <<activityId>>,
                    "activityType": <<activityType>>,
                    "activityDescription": <<activityName>>,
                    "startTime": <<startTime>>
                },
                "productInfo": <<productId>>,
                "processOrderInfo": <<processOrder>>,
                "variableInfo": <<variable_data>>,
                "activityStatusInfo": {
                    "statusId": <<Activity_statusId>>,
                    "status": <<Activity_status>>,
                    "readOnly": <<readOnly_status>>
                },
                "userConfigurationDetails": <<customActivityUser>>
            }

• loggedUserInfo: Provides the user name and token. The UAA token is required when the custom forms use the public REST APIs provided to save variables into SOADB.
• Header: Provides the activity ID, activity type as Production, Time-Based, or User-Defined, activity description, and start time of the activity.
• ProductInfo: Provides the ID, name, and value of the product.
• ProcessOrderInfo: Provides the ID, name, and value of the process order.
• Variables: Provides the list of variables with ID, name, data type, and value.
• ActivityStatusInfo: Provides information regarding whether the activity is locked, read-only state, or modifiable.
• userConfigurationDetails: Provides the user name and password configured in Plant Applications.

The following domains were tested for use of the custom form:

• Same domain: successful (same IP address)
• Cross domain: successful (with different IP addresses and ports, messages transfer between http and https)

The transmission process of data has the following limitations:

• Data cannot be transmitted using form headers, form body, or query parameters by using postmessage.
• All data is transmitted through postmessage only.