Webservices
Last updated
Was this helpful?
Last updated
Was this helpful?
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 consume 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 resources, click on Web services and comet to get the following screen where you manage the webservices:
Click on the three dots next to Add web service or use a right-click. When you select import webservice a window opens where you can give it a Service name and choose to import From web or From file. Select what applies. You pick From web if 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 webservice and WEM then knows how to access the wsdl file. If you pick From file you 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.
When the webservice has been successfully defined, you can see the service being added to the resource pane on the left hand side.
The webservice is now ready to be used in the workflows of the application.
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 open the context menu of the webservice, select service configuration and change the URL that needs to be changed. Changes in the configuration screen are automatically saved.
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 service configuration window 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.
In the Project resource pane, the newly added webservice is 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 successfully
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 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 by opening the context menu (three dots, right click) and select new webservice.
Create the operation(s) that other systems can use to access data and/or functionality that you want to expose to the outside world with the context menu and add new operation;
For every operation you need to specify the input and output fields that are needed. When you added a operation, you can find a input and output where you can add a field with the context menu;
For every operation you create a flowchart that takes care of processing input data as well as generating the output data is created. In this flowchart you add a bit of logic to handle the requests.
Document the webservice and operations, to provide all necessary information to the people that use your webservice. This option is available for the webservice and the different operations by using the context menu.
All these steps are explained in a bit more detail in the next sections
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 go to Web services and comet in the project resource pane and select Webservice (expose). You are now able to create a web service, by opening the context menu and clicking on New web service. You are then presented with the following form:
You only need to enter a name (<a-z>, <0-9>, <-> and <_>) to create a expose webservice. This will create the webservice under the chosen name and a default URL (http(s)://{portal-hostname}/webservices/expose) with portal-hostname as placeholder. The form also has a lot of other options to customize the webservice. You can change the following settings:
Enable WEM 2.7 compatibility mode Legacy option to make it make the service compatible with WEM 2.7. Only use this for this compatibility issues with old projects.
Enable JSON fields renaming
Publishing specific settings(covered in later sections):
Metadata exposure
Authentication method
You have can now find the created webservice in the resource pane under Web service (expose). With the context lets you can add operations, change the settings or edit the documentation and get the service working.
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 context menu. You have to specify the operation name (<a-z>, <0-9>, <-> and <_>). and you can add documentation.
Edit Settings When you click on this button the edit Web Service Window opens giving you the options to change the same settings as when you created the webservice.
Edit Documentation Allows you to add specific documentation that is shown when the public URL of the web service is entered in a browser.
A operation shown 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.
Every operation can define which input is needed, which output will be 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 an action flowchart and three empty folders in the operation tree:
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.
To process the input for the exposed webservice and return the correct data, you need to create a flowchart for every operation that is available in the webservice. First you have to define the input and output (and fault) fields, as explained above. Next you create the logic for the processing in the created action flowchart. This flowchart was already created when the new operation was defined, so you can immediately start to work with this 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. When the flowchart is opened it initially only shows two nodes: a Start and a End: Succes node.
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.
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 documentation button that is in the context menu of your webservice and on every operation you defined. When you click on this option, 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 Edit webservice menu when you opened from the context menu of a webservice. When you open this window, and the Metadata exposure has been set to Public URL there is a link called Open public URL in new window link, next to 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 Full WEM WSDL best for WEM consumers (so developers can use that WSDL file to set up communication from their system to your WEM application);
a link to the Basic WSDL for non-WEM consumers
a link to a JavaScript file that can be used as the client JavaScript proxy;
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
JavaScript
JSON
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.
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 for preview, staging and live:
http(s)://{portal-hostname}/webservice/[webservicename]
You can find the correct links in the Edit Webservice window for each separate environment. There are two ways to find the links: Double selecting the webservice you want to see the details of or with the context menu and selecting edit settings. You will get de webservice details, including links to the correct endpoint URLs.
The second way to exposing a webservice is through the Metadata exposure setting. You can change this by selecting the Public URL link. This setting offers two options to deal with the webservice metadata:
Public URL: This will expose all metadata information that is available through the Go to documentation page link that will appear next to the dropdown box. This links to a page that is described in the previous section.
By WSDL file: Only WSDL metadata is exposed. When this is selected, the user can click on the link on WSDL link that appears beneath the dropdown box. This will open an new browser window with a link to the webservice WSDL file;
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:
None No authentication
Client certificate The SOAP procotol validates certificates
Username/password (build-in) The SOAP protocol validates client credentials
Username/password (flowchart) Check the client credentials in the flowchart of a web service operation
Message: use this 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:
None No authentication
Client certificate The SOAP procotol validates certificates
Username/password (build-in) The SOAP protocol validates client credentials
Username/password (flowchart) Check the client credentials in the flowchart of a web service operation
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.
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 to the webservices (consume) in the resource pane, open the webservice context menu and hit Update web service. 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.
Action flowchart
Input folder
Output folder
Faults folder
The Input and Output folders are greyed to clearly show that this information type has not been specified. Maybe this information is not needed, or maybe the details still have to be specified. Once details are specified, the the greyed out folder will change to a Input and Output icon. For each of these folders you need to define which data is needed: 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 folder (e.g. Input) and now you do the same you would do when you create a data model: select the folder and open the context menu and select New field. 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.
