- Introduction to WorkXpress
- Building Your Application
- Examples and Best Practices
- Technical Manual
This shows you the differences between two versions of the page.
|
enterprise service bus - incoming soap method [2016/09/14 18:19] |
enterprise service bus - incoming soap method [2016/09/14 18:19] (current) |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| + | ====== 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 [[Action|Actions]] system is available. This ESB implements a [[http://en.wikipedia.org/wiki/SOAP|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 [[Action Type - Web Service|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 [[Action Type - WorkXpress API Key|WorkXpress API Key]] or a [[Action Type - WorkXpress Manual Authentication|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|API Key Generator]] you can easily generate an Auth Key that identifies a particular User, and would be used in conjunction with the [[Action Type - WorkXpress API Key|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 [[Action Type - WorkXpress API Return Value|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. | ||
| + | |||
| + | <code>$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(); | ||
| + | }</code> | ||
| + | ===== 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 [[Table|Tables]] and [[Field|Fields]] to read data from or to push data to and [[Action|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. | ||
| + | |||
| + | * [[Enterprise Service Bus Data Handler - WorkXpress API Actions|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. | ||
