vFire has two Application Programming Interfaces (or APIs), which enable you to develop programs that automate many common vFire transactions. This section of the documentation deals with the Classic API. For more information on the RESTful Alemba API, introduced in 9.7, see here.
The Classic API is WCF-based (Windows Communication Foundation). It is procedural – it exposes a defined set of operations (the API Transactions) that manipulate a limited set of entities.
Typical API transactions include:
- creating, updating, deleting and retrieving major vFire entities such as calls, requests, tasks, CMDB items, etc
- sending messages to Users and analysts
- additional transactions to execute queries are provided to enable clients to automate their custom transactions.
The API Transactions are exposed via a Web Service Interface, enabling them to be called from any platform and environment supporting web services (e.g. Java running on Linux).
Only documented entry points for controls and the API should be used. Any undocumented functionality is reserved for internal use only and is subject to change without notice.
API Architecture
The API is based on Windows Communication Foundation (WCF). vFire provides a WCF service and exposes an end point which can be accessed by third party applications to call standard vFire transactions.
This end point is in the location http://<machinename>/<VirtualDirectory>/ServiceManager.svc
To access this end point, you must create a WCF client (for example, using svcutil.exe) and add it to your third party application. An overview on how to generate a WCF client to connect to the Classic API is provided in Create WCF Client.
More information about WCF is provided on the Microsoft Website: http://msdn.microsoft.com/en-us/library/dd943056.aspx
Licensing and Permissions
You can develop programs to perform transactions on any part of the vFire application.
Named Analyst licensing is enforced in the Service Desk and Workflow Management transactions. Service Desk transactions can only be performed by an analyst with a Service Desk enabled role. Similarly, Workflow Management transactions can only be performed by an analyst with Workflow Management enabled role. This check is performed even when the database uses Concurrent Analyst licensing.
Analyst Permissions
The API enforces an analyst’s permissions by restricting what transactions they are able to execute. If an analyst does not have adequate permissions to execute a particular transaction, no actions will be taken and the NOPERMISSION error code and an appropriate error message will result. A few examples include:
- An analyst without Log Calls enabled will not be able to call the CallCreate transaction
- An analyst who is not a Request Manager cannot call WorkflowAuthorize
- An analyst who is not an Approver cannot call TaskComplete for an approval
- An analyst cannot call ObjectAttach for a User unless they are configured for Person Object Update.
These restrictions do not extend to checking ownership of an entity such as taking action on a call owned by another analyst when the logged in analyst does not have Call Take Over rights. In these instances the internal vFire logic may or may not execute the requested action successfully and the API will not be able to report an error.