Understanding the Job Submission Web Service

LDD 5.x provides an interface called the Job Submission API (JSAPI) that allows web service–capable client software to interact with an LDD system. It supports both Representational State Transfer (REST) and SOAP web services. Client applications (such as eSF applications, the Microsoft Windows application software Select'N'Send, Lexmark Document Server Ports, and other applications) can use these services to run an LDD script or profile. Using JSAPI, the client software can also pass extra metadata to the running script or profile for additional processing or data capture.

Through the web service, clients can do the following:

The following requirements must be met for the web service to be available to a client:

Using REST JSAPI

REST JSAPI is available only in LDD 4.6.4.1 or later.

Notes:

Use the following HTTP methods when sending requests to the server:

The base URI for RESTful JSAPI is http://loadbalancer:9780/lmc/rws/jsapi, where loadbalancer is the name or IP address of the load balancer.

Submitting jobs

Sample request
URI: /jsapi/v1/jobs
Method: POST
Version: v1
Content-type: multipart/form-data
HTTP Form Parameters: (*Required parameter)

The following table lists the HTTP form parameters used when submitting a job:

Parameter key or object

Value type

Description

* Required parameter

profileName*

String

The name of the LDD profile to execute that is in an LDD SDK solution installed on an LDD system.

For example, use Test SNS with the TestSNS example solution.

authId*

String

The name of the user who submitted the job.

clientIPAddr*

String

The IPv4 address of the client submitting the job.

Note: IPv6 addresses are not supported.

clientHostName*

String

The host name of the client submitting the job. A fully qualified domain name (FQDN) is preferred.

Note: If the host name cannot be determined, then use the IP address.

clientMACAddr*

String

The network card MAC address of the client submitting the job.

For example, 12:BA:4F:67:91:B4.

submitTime*

Long

The time on the client when job submission started.

Note: Use POSIX time format. For example, 1340125377 GMT.

appId*

String

The application ID where the job is coming from. Use one of the following IDs:

  • PNS—Use for jobs sent from LDD printer ports.

  • SNS—Use for jobs sent from the Microsoft Windows application software Select'N'Send for LDD.

  • eSF—Use for jobs sent from eSF applications.

  • LSP—Use for jobs sent from Lexmark Solutions Platform (LSP).

  • mobile—Use for jobs sent from mobile applications.

Note: The TestSNS example solution only looks for PNS and SNS IDs.

resolver

String

Use either of the following:

  • software—Use for clients that are associated with a software client group and client software script or profile.

  • hosted—Use if the client is not associated with LDD software client group settings.

Note: If no value is added, then the parameter defaults to software.

language

String

The language used by the client.

Use the format ISO 639-1_ISO 3166-1. For example, en_US. The first two letters are important, and the next two letters are used only to distinguish between Simplified (zh_CN) and Traditional (zh_TW) Chinese.

Notes:

  • This language ID format is used by Lexmark printers.
  • For more language strings, navigate to the LDD SDK script reference, and then click taskInfo > language information (taskInfo.language). You can also open a Web browser and search for “ISO 639-1” and “ISO 3166-1.”
  • If no value is added, then the parameter defaults to en_US.

xyz

String, integer, etc.

Other metadata (key and value pairs) that is needed by the specific profile launched by the job submitted.

file object

File object

File binary, file name, file extension, etc.

The key name must be prompt.[x].file.[y], where x is the scan prompt number and y is the number of the file returned by the prompt. For example, prompt.0.file.0. x and y are both zero-based.


201 Created indicates a successful response, and the HTTP header value indicates the new resource location.

Sample response
201 Created
Location: http://xxx.xxx.xxx.xxx:9780/jsapi/v1/jobs/123456
Content-Type: application/json
[json-data]
Sample success JSON response
{
"jobID": "123456"
}

If the submission fails, then one of the following errors is returned:

Sample error JSON response for a 403 error
{
"reason": "client software is not licensed"
}

Querying a job status

Sample request
URI: /jsapi/v1/jobs/{jobID}
Method: GET
Version: v1
Parameters: (*Required parameter)

{jobID} is the ID returned from the submit job request.

The following table lists the keys returned when querying a job status:

Key

Value type

Description

jobID

String

The ID of the job you are querying.

state

String

The status of the job you are querying. The status can be one of the following:

  • Running—The profile initiated by the job is still running.

  • Completed—The profile initiated by the job is completed.

  • Error—The profile initiated by the job is stopped because of an error.

percentComplete

Integer

The percentage of how much the profile initiated by the job is completed.

Note: If the percentComplete value is not 100 or the state value is not error, then do not update percentComplete in the profile.

solutionName

String

The name of the solution on the LDD system that contains the profile.

taskName

String

The name of the task or script running on the LDD system for the profile.

submitTime

Long

The time on the client when job submission started. The returned time is in POSIX time format. For example, 1340125377 GMT.

startTime

Long

The time on the LDD system when the job started. The returned time is in POSIX time format. For example, 1340125377 GMT.

Note: If the job is not started, then this key is not added in the returned JSON data.

endTime

Long

The time on the LDD system when the job ended. The returned time is in POSIX time format. For example, 1340125377 GMT.

Note: If the job is not started, then this key is not added in the returned JSON data.

authID

String

The name of the user who submitted the job.

clientIPAddr

String

The IPv4 address of the client submitting the job.

Note: IPv6 addresses are not supported.

clientHostName

String

The host name of the client submitting the job.

Note: If the host name cannot be determined, then the IP address appears.

clientMACAddr

String

The network card MAC address of the client submitting the job.

appID

String

The application ID where the job is coming from. The ID can be one of the following:

  • PNS—For jobs sent from LDD printer ports.

  • SNS—For jobs sent from the Microsoft Windows application software Select'N'Send for LDD.

  • eSF—For jobs sent from eSF applications.

  • LSP—For jobs sent from Lexmark Solutions Platform (LSP).

  • mobile—For jobs sent from mobile applications.

Note: The TestSNS example solution only looks for PNS and SNS IDs.

language

String

The language used by the client.

srvIPAddr

String

The IP address of the LDD server processing this job.

srvHostName

String

The host name of the LDD server processing the job.

Note: If the host name cannot be determined, then the IP address appears.

srvThreadName

String

The name of the thread that is processing the job. For example, workflow-29.


Sample success JSON response
200 OK
Location: http://xxx.xxx.xxx.xxx:9780/jsapi/v1/jobs/123456
Content-Type: application/json
Content-Length: xxxx
{
"jobId": "123456",
"state": "running",
"percentComplete": 40,
“solutionName”: “TestSNS”,
“taskName”: “testsns”,
“submitTime”: 1340125377,
“startTime”: 1340125400,
“authId”: “smith”,
“clientIPAddr”: “10.190.64.123”,
“clientHostName”: “my-pc.area.company.com”,
“clientMACAddr”: “12:BA:4F:67:91:B4”,
“appId”: “mobile”,
“language”: “en_US”,
“srvIPAddr”: “10.190.64.75”
“srvHostName”: “lddsrv1.area.company.com”
“srvThreadName”: “workflow-29”
}

Using SOAP JSAPI

SOAP JSAPI is available in LDD 4.3.x.x or later. We recommend using RESTful JSAPI instead of SOAP JSAPI to work with your client software applications. For more information, contact your Lexmark representative.

The following table lists the methods used with the SOAP Web Service:

Method

Target

Description

Parameters

Return values

start

Load balancer

Initiates a job submission session.

  • resolver—The resolver used to determine the device group, solution, and task settings. The default resolver uses clientIP and profileName only.

  • protocol—The protocol used to extract prompt answers from the metadata. The default is webdav.

  • authId—The client user name.

  • clientIP—The client IP address.

  • deviceGroup—The device group associated with the job.

  • profileName—The profile used for the job.

  • sessionID—The session ID, which must be used in later calls.

  • tomcatIP—The address of the LDD server, which must be the target for later calls.

  • scanUrl—The WebDAV folder where documents are submitted.

post

WebDAV

Submits files in response to ScanPrompt.

See the WebDAV documentation

metadata

LDD server

Provides answers for other prompts.

  • continue—Indicates that more metadata follows.

  • scan.x.file.y—The path of a scanned file in the WebDAV repository. x indicates the sequence number of a scan prompt, and y indicates the sequence number of a file from that scan prompt. x and y are both zero-based.

Reserved.

nextPrompt (optional)

LDD server

Requests for the next prompt.

sessionID—The session ID returned from the initial start call.

return nextPrompt—The parameters of returned changes based on the prompt type.

finish—Shows the finish button.

back—Lets users go to the previous prompt.

type—Prompt type.

queryTaskStatus (optional)

LDD server

Calls this method with the sessionID to determine if the job is successful.

sessionID—The session ID returned from the initial start call.

percentComplete—The percentage of the job completion that is updated as the script runs.

id—The session ID from the start of the job.

status—Shows the status of the job.

startTime—The time when the job started.

endTime—The time when the job ended.