Sync Improv

Improvising Integration

Calling a LynX Business Process (through the web service)

Leave a comment

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.

Web Service Methods

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

Xsd2Code1

Xsd2Code2

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).


    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;
    }

This function creates an XML document that looks like this:

<?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>

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:

    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!");
      }
    }

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

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s