Hosting a SOAP web service
Below you will find a document describing the migration path to migrate your hosted SOAP web service on runtime level to the latest generation runtime. For the key aspects of the new generation compared to the current generation, please read this fundamental.
Should you have any questions, please get in touch with academy@emagiz.com.
1. Prerequisites
- Advanced knowledge of the eMagiz platform
- A thorough understanding of your eMagiz model
2. Key concepts
- This migration path allows you to maintain your hosted SOAP web service in the 3rd generation runtime
- Consequences of this migration are:
- Your all-entry will be split up into seperate entries
- Your WSDL will be generated based on your system message
- The system message will be altered based on your configuration in Design by adding a new root entity named Send{givenname}Request
- This alteration of your system message will not impact your transformation towards your data model
- HTTP Settings now need to be configured under Deploy -> Architecture
3. Technical Migration Path
As part of the "Transfer Settings from Design" step in the general migration path on migrating to the 3rd generation runtime you will see an additional option displayed below this option called "Split Combined Entries". After you have migrated your SOAP web service to the 3rd generation runtime you will need to split the all-entry directly after the migration is finished.
As a result of this step all shared resources, such as the WSDL and the security, will be moved to the infra flow and the all-entry will be splitted into seperate entries. Once this is done you as a user need to execute several steps per entry before deploying your solution to any environment.
3.1. Clean up the entries
The starting point of our solution, which we are going to migrate, is the following SOAP web service that has two integrations linked to it.
After eMagiz notifies you that the split of the all-entry was successfull you need to execute some manual actions before adding the new flows to your release. The bulk of the manual changes needed should be performed in each of the splitted entries. After migration each entry will contain all functional components that were present before in the all-entry as we cannot determine which functional components are actually needed to handle a specific operation. So for each entry you need to remove all functional components that are not relevant for the operation that is related to the entry your are currently editing. If you do not do this, the all entry is still in the release.
When opening one of the entries after migration it looks as follows.
To remove all components that are not relevant anymore in this entry please enter "Start editing" mode. In this mode you can remove all irrelevant components from this entry. In this example that would be all components that have something to do with the bravo operation. The result will be something like this.
Subsequently you need to unlink the default resources from the entry as they are not needed in the entry flow anymore. As a result no resources are linked to the entry anymore.
3.2 Check the system message
As a result of the migration eMagiz will have added a Send{givenname}Request entity as a root entity to your system message (and Send{givenname}Response should you have a synchronous flow linked to your hosted SOAP web service). You should verify this, including the namespace, for each of your onramps. Once done we can continue with the final step of the migration in Create.
3.3 Reset the infra flow
Because eMagiz cannot determine for itself which components belong to which entry several shared components cannot be generated correctly upon pressing the "Split Combined Entries" button. As a result you should manually reset the infra flow after you have succesfully cleaned up all entries and checked all onramps. This will ensure that all shared components will be generated in such a way that the functionality will work for you as it did before.
3.4 Add the splitted entries to a release
Now that we are finished in Create it becomes time to deploy our changes to the Test environment. To add the new flows, particularly the new entries, to your release you need to execute the following steps.
- Create a new release
- Access the context menu and press "Details"
- In the pop-up that follows search for the infra flow of the runtime your are migrating
- Select the latest infra flow of the runtime your are migrating
- As a result eMagiz will automatically add the splitted entries to your release and will update the Release overview accordingly
After you have done this successfully the release overview should display the migrated runtime as follows.
3.5 Check the Runtime Settings
One last step of the migration is to check the runtime settings of the runtime you are migrating under Deploy -> Architecture. This is a new piece of functionality that allows you define the port on which the SOAP web service needs to be running (and optionally SSL settings when running it on-premise). You can access these settings via the context menu on runtime level.
Once you have selected this option a pop-up will appear showing you among others the HTTP settings. The HTTP enabled option needs to be enabled for a SOAP web service and when we look at the advanced tab we need a reference to the port we will use here (which can be a property reference).
3.6 Check your route settings
For cloud hosted endpoints you are already used to defining a route configuration for your endpoints. With the 3rd generation runtime you also need to do this for your on-premise hosted endpoints. When configuring the route you need to take the following into account:
- The port configured under the route must match the port defined under the Runtime settings configuration
- The DNS left-most label has no effect and can be filled with anything
- Make sure to link the correct container to your route
3.7 Deploy the migrated SOAP web service to an environment
To deploy this new configuration to your environment you need to execute step 4.4.2 (Update a subsequent runtime) of the default migration path (or step 4.4.1 should this be your first 3rd generation runtime).
4. Key takeaways
- This migration path allows you to maintain your hosted SOAP web service in the 3rd generation runtime
- Consequences of this migration are:
- Your all-entry will be split up into seperate entries
- Your WSDL will be generated based on your system message
- The system message will be altered based on your configuration in Design by adding a new root entity named Send{givenname}Request
- This alteration of your system message will not impact your transformation towards your data model
- HTTP Settings now need to be configured under Deploy -> Architecture