You are not logged in. Login  or register.

Web Services

Links

XEP Online is designed to be integrating into your business processes. This means your existing applications can remotely generate PDF documents with no need to purchase, install, configure, and maintain your own XSL-FO to PDF formatter.

To make use XEP Online in your applications, you have to:

  • Read this page to become familiar with technical details on integration;
  • Read and Agree with the End User License Agreement;
  • Create a free user account;
  • Use an existing or make your own client application block by either of the following ways:
    • Use pre-compiled Client Tools (requires Windows and .NET Framework 4.0);
    • Reuse the sources (TODO link) to integrate into your application (requires Windows, .NET Framework 4.0, and a development environment);
    • Look at the sources (TODO link) to make your own client code by using a similar approach.

See the following sections for more details.

Integration

We provide you the following ways to integrate with our Web services:

  • Aditya — SOAP Web service
  • Chandra — REST Web service
  • Client tools — downloadable and installable tools

Our client tools provide an out-of-the-box solution. They can be used on a standalone basis or integrated into another application. You can integrate the client tools via command line interface or program API. The important advantage is that you do not need to rewrite your integration mechanism, if you decide to switch from our Web service to an XEP rendering engine installed on your computer or on a local or remote server.
If you feel that you need other ways to integrate our Web services into your application, you can always write your own client that supports our SOAP or REST protocol.

Services

There are two services, Aditya and Chandra. Basically, they are very similar, except the basic technology they are using.

Aditya service is a SOAP-based service implementing XEP Online protocol.

Location: http://online.xep.com/RenderX.WebServices/Aditya.asmx

WSDL: http://online.xep.com/RenderX.WebServices/Aditya.asmx?WSDL

Chandra is a REST-based service.

Location: http://online.xep.com/RenderX.WebServices/Chandra.svc

 

Description of the SOAP protocol

The protocol consists of several methods available for remote calling. See the list below for available methods.

All methods require an Authentication Header containing user information. An Authentication Header should have a name of AuthHeader and must have the following fields:

  • Username: string
  • Password: string

Example:

  <soap:Header>
    <AuthHeader xmlns="http://renderx.com/webservices/soap/">
      <Username>string</Username>
      <Password>string</Password>
    </AuthHeader>
  </soap:Header>

 

Method: Format

Description: Format

Parameters:

  • xml: string
  • systemId: string
  • mimeType: string
  • Attachments: array of Attachment type
    • Uri: string contains relative URI for the referenced document (e.g. an image), exactly as it is referenced in the original XSL-FO;
    • FileContent: base64binary an attachment;

Returns: FormatResult object

  • Status: booean value, Success or Failure;
  • ResultFile: base64binary, a result PDF document;
  • Messages: Array of string; Each string contains formatter messages;
  • MissingAttachments: Array of string; Contains a list of attachments referenced in the document but not passed as input parameters;

Format method performs actual formatting of XSL-FO document passed in a xml parameter.

See also:

Description of the REST protocol

RESTful service accepts formatting requests via HTTP REST interface. The service formats submitted XML documents with the RenderX XEP engine and replies with XML response which contains a formatting log and a link from which the formatted PDF document can be downloaded.

You can use REST API to interact programmatically with this service. api.xep.com API provides access to the formatting service via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The response format is XML. Your method will be the standard HTTP POST method. You can send either standalone XSL-FO files ("xml" field) or XML file with its stylesheet ("xml" and "xsl" fields).

If you're constructing the POST query manually, it should look something like the following sample. All line endings must be \r\n. 

POST /RenderX.WebServices/Chandra.svc/format HTTP/1.1
User-Agent: curl/7.23.1 (x86_64-pc-win32) libcurl/7.23.1 OpenSSL /0.9.8r zlib/1.2.5
Host: online.xep.com
Accept: */*
Content-Length: 99071
Expect: 100-continue
Content-Type: multipart/form-data; boundary=----------------------------79e05a24ee21

------------------------------79e05a24ee21
Content-Disposition: form-data; name="xml"; filename="hammer.fo"
Content-Type: application/xml

{RAW XML DATA}

------------------------------79e05a24ee21
Content-Disposition: form-data; name="Images/rx-logo.svg"; filename="rx-logo.svg"
Content-Type: application/octet-stream

{RAW IMAGE DATA}

------------------------------79e05a24ee21
Content-Disposition: form-data; name="Images/brick.jpg"; filenam
e="brick.jpg"
Content-Type: application/octet-stream

{RAW IMAGE DATA}

------------------------------79e05a24ee21
Content-Disposition: form-data; name="Images/can.jpg"; filename="can.jpg"
Content-Type: application/octet-stream

{RAW IMAGE DATA}

------------------------------79e05a24ee21
Content-Disposition: form-data; name="mimetype"

application/pdf
------------------------------79e05a24ee21--

The multipart boundary should be randomly generated and should not occur anywhere inside the payload data. Also, don't forget the line ending after your {RAW * DATA} and before the final boundary.

If your formatting request is successful then the response should look something like this. 

<FormattingResult xmlns="http://schemas.datacontract.org/2004/07/RenderX.WebServices" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
	<Messages xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
		<a:anyType i:type="b:string" xmlns:b="http://www.w3.org/2001/XMLSchema">openState validate</a:anyType>
		<a:anyType i:type="b:string" xmlns:b="http://www.w3.org/2001/XMLSchema">event validation OK</a:anyType>
<!-- Log lines skipped -->
		<a:anyType i:type="b:string" xmlns:b="http://www.w3.org/2001/XMLSchema">closeState generate</a:anyType>
	</Messages>
	<MissingAttachments xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
	<Result>(MIME-ENCODED CONTENT)</Result>
	<Status>Success</Status>
</FormattingResult>

You can also use the cURL command line tool for submitting formatting requests to the service. In that case cURL acts as a client and you don't need to write your own program. Below you can see several examples which demonstrate the most common usages. You can turn on tracing to find out the underling request format which is required when interacting with the service.

Formatting standalone XSL-FO file:

curl
-F "xml=@color.fo;type=application/xml"
http://online.xep.com/RenderX.WebServices/Chandra.svc/format

Formatting XSL-FO file with images:

curl
-F "xml=@bgimage.fo;type=application/xml"
-F "image1=@spots.jpg;type=image/jpeg"
http://online.xep.com/RenderX.WebServices/Chandra.svc/format

Formatting XML file with XSLT stylesheet:

curl
-F "xml=@hammer.xsl;type=application/xml"
-F "xsl=@hammer.xsl;type=application/xml"
http://online.xep.com/RenderX.WebServices/Chandra.svc/format

A complete example:

curl
-F "xml=@hammer.fo;type=application/xml"
-F "Images/rx-logo.svg=@Images/rx-logo.svg;type=application/octet-stream"
-F "Images/brick.jpg=@Images/brick.jpg;type=application/octet-stream"
-F "Images/can.jpg=@Images/can.jpg;type=application/octet-stream"
-F "Images/hammer.jpg=@Images/hammer.jpg;type=application/octet-stream"
-F "Images/plank.jpg=@Images/plank.jpg;type=application/octet-stream"
-F "Images/screw.jpg=@Images/screw.jpg;type=application/octet-stream"
-F "Images/nail.jpg=@Images/nail.jpg;type=application/octet-stream"
-F "Images/box.jpg=@Images/box.jpg;type=application/octet-stream"
-F "mimetype=application/pdf"
http://online.xep.com/RenderX.WebServices/Chandra.svc/format

There are two ways utilizing RESTful service with a custom application:

  • Create a proxy class using a tool provided by a development environment;
  • Roll up your own tool that implements the required HTTP Methods;

Security

You need to create a user account to use our free service. Anonymous login is not supported by the Web service APIs, yet you can use the Web application (which runs in browser) without creating account or logging in.

Client Tools

XEP Assistant

XEP Assistant is a GUI-based Windows application.

XslDriver

...

XSL Driver is a command line tool which is easy to integrate in any Windows-based environment. It has the following features:

  • Interactive or automatic processing;
  • A comprehensive configuration file to manage all XEP Online services used (local and remote) and user management;
  • Optional XML+XSL transformation
  • Optional use of MVP.XML transformation library for XSLT 2.0 processing
  • Gathering resources rereferenced in the original XSL-FO document
  • Forming a SOAP or REST request and processing server response
  • Error logging

Command-line parameters:

[-version][-quiet]
[-service <servicename>]
[-res ask|send|skip|yes|no]
[-xml] <infile> [-xsl <stylesheet> {-param <name=value>}]
[-pdf | -ps | -svg | -xep <outfile>]
-service       Specifies a named service listed in App.config
               Default service is marked with default="true" attribute.
-res           Specifies behavour for external resources referenced in XSL-FO. 
    ASK        List the files and wait for user input
    SEND | YES Automatically send to server (see manual for SECURITY warning)
    SKIP | NO  Never send additional files (default)

ActiXEP

...

Downloading

Along with compiled versions, XEP Online Client Tools are available in open source form as well: (TODO link)

You may use these sources to build your own command-line or GUI-based client application to integrate with XEP Online formatting service or just look at the sources to build your own client tool, using your favorite development environment.

Compiling

XEP Online Client tools are developed in C#.NET.

Requirements:

  • .NET Framework 4.0

Using

Depending on your requirements, you may use XEP Online Client Tools in several different ways:

  • For simple use cases or demonstration purposes, use XEP Assistant as it seems to be simplest and most visual;
  • For integrating with popular XML Editors, use XslDriver command-line tool;
  • For initial integration, or development prototyping, use XslDriver for simple command-line invocation;

Writing Your Own Client

In case of using another development environment (not Windows/.NET), you may consider writing your own client tool. The sources of XslDriver or XEP Assistant will be of a good use to see how to gather all necessary data, form a server request, and process its response.

Preparation:

  • Make an user account with XEP Online service;
  • Decide which XEP Online service you will be using;

Processing an arbitrary document:

  • If it is XML + XSL, run an XSL transformation to form a single XSL-FO file;
  • Run through the XSL-FO file to detect all usages of external resources, e.g. images or fonts (optional, see below);
  • Form a SOAP or REST request, containing the following data:
    • Authentication information;
    • XSL-FO document
    • Attachments
  • Submit a request and wait for a response;
  • Check if any attachments are missing; If so, retrieve the missing ones and re-submit your request;
  • Display formatting messages;
  • Save, display, or otherwise use the result PDF document;

Other Programming Languages

Although XEP Online Client Tools are written in .NET environment, it is easy to integrate XEP Online Web Services into any development framework, provided that the client computer has Internet connectivity. Review the topics above for general guidelines how to do it.

Alternatively, we can develop a client code for you. Please Contact Us to request.

Integration with XML Editors

The client tools can be integrated to work with popular XML editors. See the following page for detailed instructions: Integration XEP Online Web Services with XML Editors.

Copyright © 2012 RenderX. Portions copyright © by original authors, rights reserved, used by permission.       Design by DjangoSlingshot.com