Enterprise Service Bus - Incoming SOAP Method

Purpose

The Incoming SOAP Method ESB gives the software developer the tools to generate an API to access data from a WorkXpress application, add data to a WorkXpress application, or perform a series of actions in a WorkXpress application; the full power of the WorkXpress Actions system is available. This ESB implements a SOAP based API for external developers to use.

This feature will be available in Platform Version 14.07.972.

End User Experience

The End User, in the context of an API, is an external developer that needs to interact with a WorkXpress application. The exact details of how to interact with the API created via the ESB system will vary depending on the external developer's choice of programming language or library. For example they could be using Dot Net, Java, Ruby, PHP, or even WorkXpress via the Web Service action.

WSDL

In all cases the external developer will need a wsdl to tell their application what methods are being made available and what parameters each SOAP method will need to perform its operation. The wsdl is located at {url for your application}/api/soap.php?wsdl, for example https://myapp.workxpress.com/api/soap.php?wsdl.

Authentication

Usually an API is secured so that external developers needs permission before accessing data from an application. When a SOAP ESB is called the WorkXpress platform begins by running the Authentication trigger on that ESB. This trigger ends when either a WorkXpress API Key or a Manual Authentication Action is executed.

An important part of the authentication process is telling WorkXpress which User it will be operating as. Through use of the API Key Generator you can easily generate an Auth Key that identifies a particular User, and would be used in conjunction with the WorkXpress API Key Action. In addition to the WorkXpress API key system it is possible to develop a custom authentication scheme using evaluations and the Manual Authentication Action, however keep in mind that this Action requires a User be defined. If an open API is required then the manual authentication action can be used without prior evaluations to always automatically allow access, however this should be very rare and is not advised.

Processing

Once Authentication is successful the ESB moves on to it's Processing trigger. As with the Authentication Trigger all input parameters are available to the Software Developer through the Runtime Value system in each Expression. Here the Developer writes the actions that make this API Call have meaning. Most external developers are calling the API to get a return of some kind from your system, and you will provide that return with the Return Value Action.

Example

The following is an example of how an external developer using PHP might interact with a WorkXpress application that defined a SOAP web method called formatTimeStamp that expects 2 parameters: a WorkXpress API key and a timestamp.

$auth_key = 'YOUR API KEY HERE';
$soap = new SoapClient('https://myapp.workxpress.com/api/soap.php?wsdl');
$error_message = $formated_string = '';
try {
	
	$formated_string = $soap->formatTimeStamp($auth_key, time());
	
} catch (Exception $ex) {
	$error_message = $ex->getMessage();
}

Supporting Elements

There are no supporting elements explicitly required to implement a SOAP webservice inside a WorkXpress Application. Common elements that are used in a webservice includes Tables and Fields to read data from or to push data to and Actions to perform operations inside the application. For example a SOAP method called contactName(contactID) would need a table to represent the contacts and two fields one for the contact name to return and one for the contact id to find the record with.

Options

There are two configuration options for this ESB profile.

  • Method Name - This is the function name that will be called by the end user in their code / application
  • Input Parameters - This is a list of parameters that the method will need to perform its operation. These pieces of data will be made available to the software developer to use in the actions that implement the API call.

Data Handlers

There is currently only one data handler available for this data source.

  • WorkXpress Actions: API - This data handler allows the software developer to generate actions to save values on records like the currently logged in user or to create new records and save the values on them. The full power of the actions system is available.
enterprise service bus - incoming soap method.txt · Last modified: 2016/09/14 18:19 (external edit)
Copyright WorkXpress, 2024