How do I integrate with the XML webservice?#6

API - Developers

Every WORKetc account has it's own private SOAP/XML web service. Your webservice end-point is located at https://yourdomain.worketc.com/Xml. This page lists all web methods available -- basically *everything* that WORKetc is capable of. Most methods are locked-down for obvious security reasons, so you need to authenticate and provide the session ticket during operations.

Here is a quick run-down on how you can easily leverage Veetro in your .NET Winforms/Web applications.

1) Enable remote webservice access in WORKetc

WORKetc’s web service comes locked down by default. Simply navigate to Settings -> Security, and enter an IP address/range for which you wish to enable access.

2) Create a new Visual Studio project
Open up Visual Studio 2003 or later and create a new Project. For the sake of this tutorial I am just going to create a basic Windows Form.

3) Add your web reference
In your solution explorer, right-click your Project and select "add web reference … "

In the Add Web Reference dialog, simply enter youraccount.worketc.com/Xml. If desired you can enter a more friendly web reference name such as “WORKetc”. Press Add Reference.

Important note about Windows Communication Foundation (WCF) service references:

If you're using the newer Windows Communication Foundation (WCF) soap service reference (instead of legacy "Web Reference") you might want to find & replace "\[System.Xml.Serialization.*(*Order=*)\]" with nothing in your Visual Studio Reference.cs file so that changes to the API don't silently break your reference definition. The [Order()] attributes are not required and they make service references far less robust.

4) Write some code...

About Permissions

The WORKetc SOAP web service requires you to authenticate before calling any non *WebSafe method. Employees are allowed to call web methods based on their assigned security credentials. For instance, you will invoke a permission error if you try call a finance method from an account which does not have permission to the Finances feature in the application.

To create a session key, you should call AuthenticateWebSafe( .. ). You may then include "VeetroSession: {your key}" as a HTTP cookie or HTTP request header.

If you're using .NET to interop with WORKetc, here's some sample code which demonstrates how to create a session key and use it for subsequent calls.

WORKetc.VeetroWebServiceMethods service = new WORKetc.VeetroWebServiceMethods();

// Ensure the service URL is correct, use your account!
service.Url = "http://youraccountdomain/Xml";

WORKetc.AuthenticateResult res = service.AuthenticateWebSafe("user@domain.com", "password");
if (res.Code == WORKetc.AuthenticateCode.Success)
{
   // We have a valid session, add to cookies or http header
   service.CookieContainer = new System.Net.CookieContainer();
   service.CookieContainer.Add(new System.Net.Cookie("VeetroSession", res.SessionKey, "/", new Uri(service.Url).Host));

   // Call some Employee-only method
   WORKetc.Entity[] ar = service.GetAllEntities();
   System.Diagnostics.Debug.WriteLine(ar.Length);

}
else
{
  // login failed
  System.Diagnostics.Debug.WriteLine("Login failed with " + res.Message);
}

Basic Example

Now that you have the entire platform at your command, let’s create a new person in our Address Book. Here is some simple code to create a new contact:

void AddPerson()
{

   // Instantiate the webservice
   WORKetc.VeetroWebServiceMethods service = new WORKetc.VeetroWebServiceMethods();

   // Ensure the service URL is correct, use your account!
   service.Url = "http://youraccountdomain/Xml";

   WORKetc.AuthenticateResult res = service.AuthenticateWebSafe("user@domain.com", "password");
   if (res.Code != WORKetc.AuthenticateCode.Success)
   {
       // Login has failed here..
       MessageBox.Show("Login failed with " + res.Message);
       return;
   }

   // We have a valid session, add to cookies or http header
   service.CookieContainer = new System.Net.CookieContainer();
   service.CookieContainer.Add(new System.Net.Cookie("VeetroSession", res.SessionKey, "/", new Uri(service.Url).Host));

   ///
   // Create a new person object
   //
 
   Person p = new Person();
   p.EntityID = 0;    // EntityID zero will tell the service, this is a new contact.
   p.FirstName = "John";
   p.Surname = "Doe";
   p.Email = "john@doe.com";

   // Create an address
   Veetro.Address a = new Veetro.Address();
   a.Country = "Canada";
   a.Phone = "902 555 0000";
   a.PostalCode = "B0J 3C0";
   a.StateOrProv = "NS";
   a.Street = "Some Street";
   a.Suburb = "Sherbrooke";
   p.Addresses = new Veetro.Address[] { a };

   // Save the person. SetPerson will return the object again
   // except it will be populated with it's new unique EntityID.
   try
   {
      p = service.SetPerson(p);
      MessageBox.Show("New Person created with ID " + p.EntityID + ".");
   }
   catch (Exception x)
   {
        MessageBox.Show("Create person failed with " + x.Message);
   }
}

If we invoke our AddPerson() method above, we should get a the full Person object returned from the web service, complete with our unique "EntityID".

Hint: All web service methods in WORKetc allow you to create a new object by supplying zero (0) as the Unique Identifier. This instructs WORKetc to make a fresh record, and since all SetXXXXX() web methods return the saved object, you immediately gain a reference to the object's Unique Identifier(s).