SOAP API for Web Services Integration
The Web Services API is used to create custom front-end applications for Loftware Enterprise SP. The Simple Object Access Protocol (SOAP) API for Web Services integration provides basic and advanced functionality, including printing, document searching, device searching, and the ability to submit stacked jobs.
SOAP
Simple Object Access Protocol (SOAP) is a standard method of transmitting data over computer networks. SOAP uses XML to encapsulate either a request or a response in an envelope. When SOAP is implemented, it abstracts the client architecture from the server, so any client computer that can generate and parse the SOAP envelopes can function. SOAP can be used by a desktop application, web browser-based application, or mobile application.
Each SOAP request to Loftware Enterprise SP must be in the format specified by the Loftware Enterprise SP Web Services Description Language (WSDL). Every SOAP request must have an envelope. For requests to Loftware Enterprise SP, an envelope must include a security header for authentication and a request body.
In Loftware Enterprise SP, when you create a SOAP Web Service data service using the Loftware Enterprise SP WSDL, you can select an operation envelope template. Each envelope template includes a body that you can edit. You can also select a security header template.
All responses to a request have a SOAP envelope. Responses typically do not include a header, but do include a body that contains a return element.
The value of the success attribute of the return element determines the contents that follow it. If there is a successful result (success="true"), then the response data includes a result element containing data related to the fully-qualified name that was submitted. The result element may be preceded by one or more additionalData elements containing children.
Responses also contain an element that references itself. For example, if a request for getVersion was sent, getVersionResponse would be sent back to the client computer.
Tip: For the syntax of a SOAP Response to specific type of SOAP Request, see the Functions section that follows.
Functions in SOAP Request and SOAP Response
To view envelope templates and header templates that use the Loftware Enterprise SP WSDL, do the following when creating or editing a SOAP Web Service data service.
- For WSDL URL, enter the following URL, substituting the IP address of your Loftware Application Server for <Server IP>
http://<Server IP>:8080/spectrum-server/webServices/spectrumservices?wsdl
- For Envelope, click Get WSDL Operations, and then select an operation envelope template. An envelope template containing the selected function is displayed, including a body that you can edit. For information about each envelope template, see the reference that follows.
- For Security Header, select a header template to use with the envelope where appropriate.
Alternatively, you can view the list of available functions at the following URL, substituting the IP address of your Loftware Application Server for <Server IP>. The functions are listed in the LoftwareServices section.
http://<Server IP>:8080/spectrum-server/webServices/
The following is a reference about the SOAP functions available when using the Loftware Enterprise SP WSDL.
The following table describes the common operational functions, such as those that relate to print jobs and to the SOAP API.
| Purpose | Description | Syntax |
|---|---|---|
|
Get the SOAP version |
Return the version number of the SOAP API. |
|
|
Submit a print job |
Submit a specified print job for processing and return the ID of the job. The print job must be specified as a UserJobRequestDto. |
|
| Submit an XML print job | Submit a print job in the form of properly formatted LPS XML. | |
|
Submit an XML print job, overriding the default process |
Submit a print job in the form of properly formatted LPS XML. You can override the default process and job target folder used. |
|
|
Get the status of a print job |
Retrieve the status of a specified print job. The print job must be specified by print job ID number. |
|
|
Get the detailed status of a print job |
Retrieve the detailed status of a specified print job. The print job must be specified by print job ID number. | |
| Import an image | Import an image into the Loftware Enterprise SP environment. | updloadImage |
The following table describes the functions that relate to devices and device groups.
| Purpose | Description | Syntax |
|---|---|---|
| Get the names of device groups |
For a fully-qualified folder in Loftware Enterprise SP, return a list of all device groups in that folder. Device groups in subfolders are not included. |
|
| Get details about a device group |
Given a device group name (not the fully-qualified path for the device group), return details about the device group. |
|
| Get the names of device connections |
For a given a fully-qualified folder in Loftware Enterprise SP, return a list of the device connections in the folder. Device connections in subfolders are not included. |
|
| Get details about a device connection |
Given a device name (not the fully-qualified path for the device), return details about the device. |
getDeviceDetails |
The following table describes the functions that relate to managing device queues.
| Purpose | Description | Syntax |
|---|---|---|
| Cancel print jobs | Given a list of print jobs, cancel and remove the print jobs from their respective device queues. Optionally, set the status of the print jobs to an error status and log a reason for the error. | cancelErrorPrintJobs |
| Reserved | This function is reserved for future use. | getQueueDetail |
| Release print job | Given the fully-qualified name of a device and a print job ID in a stopped or paused device queue, immediately print the specified print job. | releasePrintJob |
|
Request a queue action |
Given the fully-qualified name of a device and a queue action, request that the queue action be performed on the device queue. |
The following table describes the functions that relate to label templates, applications, business rules, forms, images, layer objects, layouts, reusable objects, or workflow templates.
Multi-Site Deployment Functions
The following table describes the functions that relate to managing a multi-site deployment.
| Purpose | Description | Syntax |
|---|---|---|
| Initiate configuration sync | Given the name of a facility, initiate replication of objects from headquarters to that facility. | manualPlantEntitySync |
|
Initiate transaction sync |
Given the name of a facility, initiate replication of transactional data used for auditing from the facility to headquarters. |
manualPlantTransactionSync |
The following table describes the functions that relate to tag categories and tag values.
Note: As indicated in the following table, some functions are supported for use only in conjunction with objects managed with Documents permissions Documents permissions are used in Access Control to manage label templates, applications, business rules, forms, images, layer objects, layouts, reusable objects, or workflow templates. rather than all types of tagged objects.
| Purpose | Description | Syntax |
|---|---|---|
|
Categorize an object by adding a tag |
Given the fully-qualified Loftware Enterprise SP name of an object managed with Documents permissions |
addTagValueToDocument |
|
Add a new tag value to a static tag category |
Given the name of an existing static tag category and a new tag value, add the new tag value to the tag category. |
|
|
Change the name of a tag category |
Important: This function is no longer supported. Given the name of an existing tag category and a new name, change the name of the tag category. |
changeCategoryName |
|
Create a tag category |
Given a name for a new tag category and a Boolean value indicating whether the tag category should be variable or static, create a new tag category. |
|
|
Create a static tag category |
Given the name for a new static tag category and a list of tag values, create the new static tag category and specifies the tag values available for it. |
|
|
Delete a tag category |
Given the name of a tag category, delete the tag category from Loftware Enterprise SP. Tags with this tag category are removed from objects. |
|
|
Get the details for a specific tag category |
Given the name of an existing tag category, return information about the tag category. |
|
|
Get an object's assigned tag values for a specified tag category |
Given the fully-qualified path to an object managed with Documents permissions |
|
|
Get the tag categories that exist in your Loftware Enterprise SP environment |
Returns a list of the tag categories that exist in your Loftware Enterprise SP environment. Optionally, the tag values associated with each tag category can also be returned if a Boolean value is true. |
getTagCategories |
|
Get the tag categories that exist in your Loftware Enterprise SP environment |
Return a list of the tag categories that exist in your Loftware Enterprise SP environment. |
|
|
Get an object's assigned tags |
Given the fully-qualified path to an object managed with Documents permissions |
|
|
Remove a tag value from a tag category |
Given a static tag category and a tag value, remove the specified tag value from the tag category. Tags with this combination of category and value are removed from objects where they have been assigned. |
|
|
Remove a tag from an object |
Given the fully-qualified path to an object managed with Documents permissions |
|
|
Change the tag value of a tag assigned to an object |
Given the fully-qualified path to an object managed with Documents permissions |
Loftware Enterprise SP WSDL
Web Services Description Language (WSDL) is used to show client computers what functions are available and how to use them. The WSDL used by Loftware Enterprise SP is automatically generated by using the Java code developed for Web Services. Viewing the Loftware Enterprise SP WSDL can be helpful if you need more technical detail about the functions, elements, and attributes than is provided in this guide.
To view the WSDL for your Loftware Enterprise SP environment, see the following URL, substituting the IP address of your Loftware Application Server for <Server IP>:
http://<Server IP>:8080/spectrum-server/webServices/loftwareservices?wsdl