Integration Server

The Integration Server is a horizontally scalable webapp that is used in client projects for back-end integrations. The Integration Server uses the following technologies:

• Apache Camel

  A framework for asynchronous integration that provides concrete implementations of Enterprise Integration Patterns (EIP), connectivity to a wide variety of transports and APIs, and domain specific languages to wire EIPs and transports together.

• Spring Security

  Used to secure Integration Server APIs.

REST APIs

Integration Server exposes several REST APIs:

• Import/Export APIs
• Catalog Syndication APIs
• Operational Insights APIs

API Security

Integration Server should not be exposed on the public internet, as described in our Security Positioning Statement. These APIs should be restricted by network security for use by trusted, internal services.

However, as an additional layer of protection, Integration Server APIs are secured with HTTP Basic Authentication. Therefore, each Integration Server API request must include an Authorization header with the value Basic <token> where the token contains <username>:<password> as a Base64 encoded string. For example, for a user with the username of login and a password of 123456, the request must have an Authorization header with the value Basic bG9naW46MTIzNDU2. If you decode bG9naW46MTIzNDU2 using Base64 decoder, this would result into the string login:123456.

Valid login credentials for the HTTP Basic Authentication are determined based on the username and password of Commerce Manager users assigned to the built-in Web Service Access user role. For more information about this role, see Built-in User Roles.

note

We recommend that the default admin user be disabled and a custom user be created for accessing Integration Server APIs in production environments.

Velocity Email Formatting

Customizing Email

Email messages are created by ep-<topic>-email-handler modules in response to JMS (Java Messaging Service) events, and formatted by the Velocity template and properties files in ext-assets/src/main/assets/themes/electronics/default/templates/velocity/email. Changes to email format or content should be made directly in the ext-assets module.

Configuring Velocity

Velocity is a templating engine. It is used to merge data from the application with HTML templates to generate text or HTML email messages. The serviceVelocityEmail.xml file is located in the ext-integration/src/main/webapp/WEB-INF/spring/service directory. It contains settings that allow you to configure behavior of the Velocity engine.

The cacheSeconds property of the globalMessageSource bean specifies how long message source resource files are cached. In production, it should be set to -1 (infinite). For testing purposes, it can be set to a positive value. This will allows you to test changes to message source resource files without having to restart your application or servlet container.

<bean id="globalMessageSource" class="org.springframework.context.support.ReloadableResourceBundleMessageSource">
    <property name="basenames">
        <list>
            <value>/WEB-INF/misc/message-source/application</value>
            <value>/WEB-INF/templates/velocity/globals</value>
            <value>org.springframework.security/messages</value>
        </list>
    </property>
        <!-- Set cacheSeconds to -1 in Production Environment -->
    <property name="cacheSeconds"><value>${ep.velocity.cache.seconds}</value></property>
    <property name="defaultEncoding"><value>UTF-8</value></property>
</bean>

For optimal performance, the following properties on the velocityProperties bean definition should also be set:

• file.resource.loader.cache

  Set this value to true for production to cache templates in Velocity’s loader. Set this value to false for development so that changes to templates will take effect immediately.

• velocimacro.library.autoreload

  This parameter enables/disables automatic reloading of Velocity macros. Set this value to false for production.

  For development, setting this value to true will allow changes to Velocity macros to take effect without restarting the server.

• velocimacro.messages.on

  Set this value to false for production for improved performance. When developing Velocity templates, this value can be set to true to see Velocity logging and debugging information.

• runtime.log.logsystem.class

  Set this value to org.apache.velocity.runtime.log.NullLogSystem as shown below for production.

  <entry key="runtime.log.logsystem.class"><value>org.apache.velocity.runtime.log.NullLogSystem</value></entry>
  

Performance Considerations

Elastic Path has tested the current configuration under a high load of 400 virtual users, which is a usual test for this type of change. Every queue is configured to be consumed with one consumer except for the Consumer.orderConfirmationEmailHandler.VirtualTopic.ep.orders queue, that is configured with five consumers because it is the most loaded queue. If required, you can add more concurrent consumers to the existing queues by modifying the destination URI in the database.

To increase the number of consumers, perform the following steps:

1. In the database, find the setting value of the selected queue.

   For example, to set 10 number of concurrent consumers for the Consumer.customerRegistrationEmailHandler.VirtulTopic.ep.customers queue, find it in the database, by executing the following command:

   SELECT * FROM TSETTINGVALUE WHERE CONTEXT_VALUE='jms:queue:Consumer.customerRegistrationEmailHandler.VirtualTopic.ep.customers'
   

2. Update the queue URI by adding the concurrentConsumers=<DESIRED_NUMBER_OF_CONSUMERS> parameter with the following code:

   UPDATE TSETTINGVALUE SET CONTEXT_VALUE='jms:queue:Consumer.customerRegistrationEmailHandler.VirtualTopic.ep.customers?concurrentConsumers=10' WHERE UIDPK=<UIDPK_FROM_SELECT>
   

3. Restart the integration server.

   The new value is visible in the ActiveMQ web console.

   note

   Do not exceed the broker’s maximum number of connections specified in the transport URL. For example:

   <transportConnector name="openwire" uri="tcp://0.0.0.0:61616?maximumConnections=1000&amp;wireFormat.maxFrameSize=104857600"/>
   

   If exceeded, you must reconfigure ActiveMQ. For more information, see the CloudOps for AWS ActiveMQ documentation.

   You can increase the number of concurrent consumers per queue. Ensure that you use the following formula:

   maxConnections x maximumActiveSessionPerConnection < maximumConnections

   The maxConnections and maximumActiveSessionPerConnection parameters are found in the conf/Catalina/localhost/<APP>.xml file. <APP> is batch, integration, or cm.

   The maximumConnections parameter is specified as a query parameter in the transport URL. You can find the parameter in the <AMQ_HOME/conf/active.xml> file.