Sync Improv

In this post, I’ll describe how to call a (LynX) business process through the web service.
Note: This post assumes that you are calling the web service from .Net. The web service can be called by any external app that can consume web services.

Web Service Methods

LynX Web Service provides a handful of methods/operations to submit and retrieve documents (if you are wondering why you can use the same web method for different E1 functions, read my previous posts). The web service is a SOAP based web service (we are working on a REST based implementation). Here is a partial screenshot of the operations provided by the service.

To call a business process, you need to call one of the Process Document methods. In its simplest form, the Process Document method requires three parameters:

1. document: the string representation of the XML document. The document must be in Unicode (utf-16) format.
2. password: the E1 password of the user specified in the e1user attribute of the document.
3. attachmentSetID: the id of the attachment set (if attachments were submitted using the CreateAttachmentSet and AddAttachmentToSet methods)

Creating the input document

You can create the input document using any of the XML creation methods (XmlDocument, XmlWriter etc.). However, there is an easier way to do it: use the XML Schema to create a typed class and serialize the object to create the XML document. You can use xsd.exe to create the typed class. I prefer to use a tool called Xsd2Code to create typed classes as it is integrated with the Visual Studio IDE. You can download it here.

Side notes on Xsd2Code (see screenshots below):

• Make sure that you set the target framework to your framework level and the GenerateXmlAttributes property to True
• You can auto-generate the code by setting the Custom Tool property of the schema file to Xsd2CodeCustomTool

Here’s a function to create a typed object for the business process ERP.EOne.Training1 (download the solution at the end of this post).

[code language=”csharp”]

static string CreateDocument()
{
// create the document using the typed class
BusinessDocument bd = new BusinessDocument();
bd.processsettings = new ProcessSettings();
// this tells lynX which business process to execute
bd.processsettings.aelliusrequestid = "ERP.EOne.Training1";
bd.processsettings.anonymous = false;
bd.processsettings.debug = false;
bd.processsettings.e1role = "*ALL";
bd.processsettings.e1user = "E1USER";
bd.processsettings.environment = "JDV910";
bd.processsettings.keeprepository = true;
bd.processsettings.lynxapp = "LynX App";
bd.processsettings.lynxuser = "E1USER";

bd.document = new Document();
bd.document.input = new Input();
bd.document.input.AddressName = "*Test*";

// serialize the XML
XmlSerializer xs = new XmlSerializer(bd.GetType());
StringBuilder sb = new StringBuilder();
XmlWriterSettings xws = new XmlWriterSettings() { Indent = true, Encoding = System.Text.Encoding.Unicode };
using (XmlWriter xw = XmlWriter.Create(sb, xws))
{
xs.Serialize(xw, bd);
}

// this is XML document that needs to be submitted
string document = sb.ToString();

return document;
}
[/code]

This function creates an XML document that looks like this:

[code language=”xml”]
<?xml version="1.0" encoding="utf-16"?>
<aelliusconnector>
<processsettings
aelliusrequestid="ERP.EOne.Training1"
environment="JDV910"
debug="false"
processmode="object"
anonymous="false"
e1user="E1USER"
e1role="*ALL"
lynxapp="LynX App"
lynxuser="E1USER" />
<document>
<input>
<AddressName>*Test*</AddressName>
</input>
<output />
</document>
</aelliusconnector>
[/code]

Submitting the document

To call the web service, you can simply add a service reference or just reference LynXProxy, a class library that is part of the product.
Here is a function to submit the document to the web service:

[code language=”csharp”]
static void SubmitDocument(string document)
{
WebProxy wb = new WebProxy();

// set the url for the web service
wb.SetUrl("http://yourwebserice.com/lynxweservice/lynxwebservie.asmx");

// set the credentials to access the web serivce
// the web sevice supports windows integrated and
// basic authentication. these are not necessarily the
// crendentails to access E1.
// named parameters used for clarity
wb.SetCredentials(userName: "userid", password: "password", domain: "domain");

// login to E1 through the web service
// this is optional
wb.LoginUser(userID: "E1USER",
password: "e1password",
role: "*ALL", environment: "JDV910",
debug: false);

// submit the document
string output = wb.ProcessDocument(document: document, password: "e1password", attachmentsetID: 0);

// load the XML document – you can also deserialize it
// to a typed object
XmlDocument xml = new XmlDocument();
xml.PreserveWhitespace = true;
xml.LoadXml(output);

// check the status of the document
bool success = ((XmlElement)xml.DocumentElement.SelectSingleNode("document")).GetAttribute("status") == "true";

// get errors
if (!success)
{
Console.WriteLine("Document submission failed. Errors below.");

foreach (XmlElement error in xml.DocumentElement.SelectNodes("errors/error"))
{
Console.WriteLine(error.GetAttribute("description"));
}
}
else
{
Console.WriteLine("Document submitted successfully!");
}
}
[/code]

That’s it! As you can see, it is pretty straightforward to create the input and call the business process through the web service.
Here is the link to the Visual Studio (2010) solution.

LynXDemo