WEM applications can use SOAP to integrate with external systems.
SOAP “Simple Object Access Protocol” is a highly standardized and self-documenting messaging framework, where everything you can do is strictly defined in a WSDL “Web Service Description/Definition Language” document. SOAP is a very rigid integration standard, which makes it especially easy to use for novice or non-technical users, because both systems integrating with each other have a pre-defined way of communicating. When using SOAP, the data exchanged is always in the XML format, but you’ll never know, as WEM does all the translation from and to XML into the familiar WEM datamodels.
WEM can both expose from (let others integrate with your WEM Project) and consume (integrate with other systems) SOAP web services with a minimum of technical skills.
Before you can use SOAP services in your flowcharts, you need to configure the webservices that you want to be available. The same is true if you want to expose your application to external systems: you need to define the service that external systems can access.
In order to concume external SOAP services you need to specify those services in the WEM Modeler. To do this, you need to take the following steps:
- In the Project tree (Home tab), click on
Web services (consume)
You get the following screen where you manage the webservices:
- Click on
Add web service. This gives you two options:
From file. Select what applies. You pick
From webif you have a URL from which you can load the service’s WSDL (Web Services Description Language) file. This file contains the description of the web service you want to use.
If the URL points towards a .asmx or .svc file, WEM will assume this refers to a .Net webbservice and WEM then knows how to access the wsdl file.
If you pick
From fileyou either have to specify a wsdl file to upload or a zipfile in case you need multiple wsdl files (plus the xsd file) to specify the webservice.
- You now get a popup where you need to enter the URL or upload the (zip)file. You also need to specify the
Service name. This is the name you want to use within the WEM Modeler to access the webservice.
When the webservice has been succesfully defined, you see the overview of the webservice. See an example below:
You can also see the service being added to the Project tree on the left hand side.
The overview shows the service operations that are available (they are also nodes of the service in the Project tree).
The webservice is now ready to be used in the workflows of the application.
Changing endpoint configurations
In order to use the webservice, WEM needs to know the web service URL. By defaults this URL is the same for preview, staging and live environments. But if you want, you can change that. In the webservice overview simply select the
Endpoint configuration & authentication tab and change the URL that needs to be changed. Click on
configure and the changes are stored.
External webservices might require some kind of authentication in order to access them. These authentication requirements have to be defined in the WSDL. WEM supports Basic Authentication (username/password) and Client Certificate authentication. When consuming the WSDL in WEM, it should automatically recognize these requirements. In the tab
Endpoint configuration & authentication you can enter the required information (client certificate or username/password).
If WEM does not seem to recognize the requirements (this can happen because of custom non-standard definitions that WEM does not yet recognize), you won’t see the authentication fields in tab endpoint configuration. If you are sure there should be authentication, create a ticket and provide the WSDL as URL or file attachment so we can investigate how WEM should interpret this specific definition.
Details in the Project tree
In the Project tree, the newly added webservice is also visible:
Here you can also find the service operation, but you can drill down into the details. For every service operation you find:
Input: if you click on this/open the node, you can see which fields are needed as input for the service operation to be executed succesfully
Output: these are the fields that contain the result of the webservice operation
Faults: The fields that are available in case there are any errors
Using the webservice is done in flowcharts, where the same information is obviously available, since that is where you work with the actual data.
When you want your application to expose data to other systems, you can set up a webservice that other systems can access. To expose your application, you need to take the following steps:
- Create the webservice that other systems can use to access your application;
- Create the operation(s) that other systems can use to access data and/or functionality that you want to expose to the outside world;
- For every operation you need to specify the input and output fields that are needed;
- For every operation you create a flowchart that takes care of processing input data as well as generating the output data;
- Document the webservice and operations, to provide all necessary information to the people that use your webservice.
All these steps are explained in a bit more detail in the next sections
Creating a webservice
When you want your application to expose data to other systems, you can set up a webservice that other systems can access. To do this, you click on
Web services (expose) in the Project tree. You are now able to create a web service, by clicking on
Create web service. You are then presented with the following form:
You only need to enter the name you want to give the service (
Display name), as well as the
When the service is created WEM takes you to the service overview where you no need to create one or more service operations. The Service overview screen has a toolbar with two buttons:
- Edit web service – when you click on this button you can change the display and/or technical name of the selected webservice;
- Edit service documentation – Allows you to add specific documentation for the webservice. See below for details.
Creating webservice operations
Now that you have created a webservice, you can start to create one or more operations. These operations define what data or functionality is being shared with external systems. To create a new operation, simply click on
New Operation in the service overview screen. You have to specify the operation name (you cannot use any spaces or special charaters).
The operation is now shown in the service overview:
It is also available in the Project tree:
The next step to take is to define which information is needed as input for the webservice, and which information will be returned to the external system using the webservice.
Specify input, output & fault details
Every operation can define which input is needed, which output will returned and what fault information is available. The input detail is input information that the operation needs in order to successfully execute the operation. All output that is returned is stored in the output details. And in case something goes wrong during the execution of the operation, fault information is available through the fault details.
In order to define all the necessary information, every new operation creates three nodes in the operation tree:
They all start with
no to clearly show that this information type has not been specified (yet) (see image above). Maybe this information is not needed, or maybe the details still have to be specified. Once details are specified, the
nokeyword will disappear.
For each of these nodes you need to define which data is needed here: you need to add the fields and/or lists that should be given as input for the webservice. You also need to add the fields and/or lists where the results you want to return are stored. And the same applies to fault information. All this information will be part of the service definition that is used by the external systems.
To define the data that is needed: click on the node (e.g.
No input) and now you do the same you would do when you create a data model: select the fields or lists you need. When you use single-select or multi-select fields, the concepts that are referred to in these fields will be part of the service definition as well, so external systems have the correct and complete data.
When all data is specified, the final step is needed: create the flowchart that processes the request and make sure the correct data is returned.
Create operation flowcharts
To process the input for the exposed webservice and return the correct data, you need to create a flowchart for every operation that is availble in the webservice. First you have to define the input and output (and fault) fields, as explained above. Next you create the flowchart for the processing. This flowchart was actually already created when the new operation was defined, so you can immediately start to work with this flowchart. To edit that flowchart:
- Click on the operation in the Project tree. You are now in the webservice details overview where you will find all defined operations.
- Double-click on the operation to open the flowchart, or select the operation and click on
Open flowchartin the toolbar. The flowchart is opened and initially only shows two nodes: a
- Complete the flowchart where you use the input fields in your flowchart. The flowchart also assigns values to the output fields, to make sure the webservice can return the requested data. In case you run into an error situation, the flowchart can also assign data to the defined fault fields.
Document webservice and operations
The exposed webservice will be used by developers (or WEM Modelers) that want their systems to communicate/integrate with your application. In order to make that as easy as possible you can document your webservice and every individual operation. This documentation can be used to describe the webservice in general, to explain what an operation does, what input is needed, what output can be expected, etc. You can document whatever you want.
Documenting your webservice is done using the
Edit service documentation button that is in the toolbar on the top of the webservice and operation details screens. When you click on this button, you will get a documentation form:
Just hit the
Save button to save the documentation.
To document an operation, simply click on the
Edit documentation button in the operation overview screen. You get a similar documentation window as the service documentation:
This documentation is available from the
Webservice configuration tab. When you click on this tab, and the
Metadata exposure has been set to
Full documentation there is a link called
Go to documentation page, beneath the
Metadata exposure field. This is the URL to the webservice documentation page, which will look like this:
You will find the following information here:
- At the top is the service documentation, as you have specified it;
- A Resources section with links to information that is valuable for developers:
- a link to the WSDL file (so developers can use that WSDL file to set up communication from their system to your WEM application);
- a link to a Typescript definition file for a client proxy;
- An Operations section with a link to:
- a page that contains Request and Response examples for
- SOAP 1.1 & SOAP 1.2
- These example show how based on one of the mentioned protocols your webservice can be used
- At the bottom is the specific Operation documentation, as you have specified it.
- a page that contains Request and Response examples for
You are now ready to expose this webservice to external systems: publish and share the endpoint links.
When you are ready building your webservice, you need to publish the project to make it available for consumers. Your webservice will be available at 3 different endpoints:
- Preview (looking like
- Staging (looking like
- Live (looking like
You can find the correct links on the tab
Webservice configuration (next to tab
Operations), for each separate environment. There are two ways to find the links:
The first one is to click on the
Edit webservice button in the upper toolbar, when the webservice is selected in the project tree. You will get de webservice details, including the correct endpoint URLs.
The application in this example is not yet published to Staging or Live, so you see
no url available at the moment. Once the project is published to these environments this screen will display the published endpoints.
The second way to find the endpoint URL is through the
Metadata exposure field. This field offers three options to deal with the webservice metadata:
- None: no webservice metadata is exposed;
- WSDL only: Only WSDL metadata is exposed. When this is selected, the user can click on the
link on WSDLlink that appears beneath the dropdown box. This will open an new browser window with a link to the webservice WSDL file;
- Full documentation: This will expose all metadata information that is available through the
Go to documentation pagelink that will appear beneath the dropdown box. This links to a page that is described in the previous section.
It is possible to specify how the communication with the webservice is encrypted. There are three possible methods:
- None: there will be no encryption;
- Transport: the communication will be encrypted. When this option is selected, you need to specify the authentication method:
- Client certificate
- Message: this is use when the actual message itself (the content) needs to be encrypted. When this option is selected, you must:
- Choose /upload a client certificate;
- Specify the authentication method:
- Client certificate
You can specify the encryption method for each of the three environments: preview, staging and live. And each environment can have a different encryption approach.
Definition changed? Update consumer!
If you change your exposed webservice and publish it to staging/live environments, the consumers need to be updated. If your consumer is another WEM-project, just go into the webservice (consume) area, select the webservice and hit
Update webservice in the toolbar.
This is necessary when: * Input fields change; * Output fields change; * Faults change; * Security settings changed; * Operations change; * Concepts in the Ontology change, which are used in any of the input/output single/multi-select fields (ontology-concepts are made part of the webservice definition)
Any of these changes results in a change of the
contract, the definition of the webservice.
Let’s look at setting up realtime messaging.