Archive

Posts Tagged ‘msdn’

Creating SharePoint list items with PHP

March 3, 2010 17 comments

As requested, here’s an example of creating a SharePoint list item with PHP. If you read my previous post (Reading a SharePoint list with PHP) you’ll notice that the code is very similar. In fact, only the CAML query (which is contained in the SOAP request) and the Lists method has changed. Once again, I recommend following this simple guideline when coding a SharePoint application from PHP or Java :

  • Use a local copy of your SharePoints Lists WSDL file (or any other SharePoint Web Service WSDL file you’ll be using).  You’ll avoid the painful task of having to deal with Microsoft’s NTLM authentication protocol. By doing this you’ll be using basic authentication, unless your server has a special security configuration. This means less code, less maintenance, and quicker deployment. Your Lists WSDL file must be downloaded from your own SharePoint server (at the URL: sharepointdomain.com/subsite/_vti_bin/Lists.asmx?WSDL).

Here are resources that will help you construct your CAML query:

To get the code to work, you’ll need the NuSOAP library, your own local Lists WSDL file,  and of course your own personalized authentication/list variables in the code below. This code has been tested with SharePoint Online and PHP 5.3, but should work with MOSS 2007.

<?php

// Requires the NuSOAP library
require_once('lib/nusoap.php');

$username = 'yourUsername';
$password = 'yourPassword';
$rowLimit = '150';

/* A string that contains either the display name or the GUID for the list.
 * It is recommended that you use the GUID, which must be surrounded by curly
 * braces ({}).
 */
$listName = "TempList";

/*
 * Example field (aka columns) names and values, that will be used in the
 * CAML query. The values are the attributes of a single list item here.
 * If the field name contains a space in SharePoint, replace it
 * here with _x0020_ (including underscores).
 */
$field1Name = "Title";
$field2Name = "Address";
$field3Name = "Premium_x0020_customer";

$field1Value = "John Smith";
$field2Value = "USA";
$field3Value = "1";

/* Local path to the Lists.asmx WSDL file (localhost). You must first download
 * it manually from your SharePoint site (which should be available at
 * yoursharepointsite.com/subsite/_vti_bin/Lists.asmx?WSDL)
 */
$wsdl = "http://localhost/phpsp/Lists.wsdl";

//Basic authentication is normally used when using a local copy a the WSDL. Using UTF-8 to allow special characters.
$client = new nusoap_client($wsdl, true);
$client->setCredentials($username,$password);
$client->soap_defencoding='UTF-8';

//CAML query (request), add extra Fields as necessary
$xml ="
 <UpdateListItems xmlns='http://schemas.microsoft.com/sharepoint/soap/'>
 <listName>$listName</listName>
 <updates>
 <Batch ListVersion='1' OnError='Continue'>
 <Method Cmd='New' ID='1'>
 <Field Name='$field1Name'>$field1Value</Field>
 <Field Name='$field2Name'>$field2Value</Field>
 <Field Name='$field3Name'>$field3Value</Field>
 </Method>
 </Batch>
 </updates>
 </UpdateListItems>
";

//Invoke the Web Service
$result = $client->call('UpdateListItems', $xml);

//Error check
if(isset($fault)) {
 echo("<h2>Error</h2>". $fault);
}

//extracting the XML data from the SOAP response
$responseContent = utf8_decode(htmlspecialchars(substr($client->response,strpos($client->response, "<"),strlen($client->response)-1), ENT_QUOTES));

echo "<h2>Request</h2><pre>" . utf8_decode(htmlspecialchars($client->request, ENT_QUOTES)) . "</pre>";
echo "<h2>Response header</h2><pre>" . utf8_decode(htmlspecialchars(substr($client->response,0,strpos($client->response, "<")))) . "</pre>";
echo "<h2>Response content</h2><pre>".$responseContent."</pre>";

//Debugging info:
//echo("<h2>Debug</h2><pre>" . htmlspecialchars($client->debug_str, ENT_QUOTES) . "</pre>");
unset($client);
?>

Creating SharePoint list items with java: tutorial

February 15, 2010 17 comments

This post completes the 2nd part of my series of “Using external business data with SharePoint”: SharePoint Web Services and Java

When I first tried to experiment with Java and SharePoint I really wondered why Microsoft didn’t invest a bit more into interoperability concerning their SharePoint platform. The potential is here: they have a market-leading product with rich Web Services. So why only support Microsoft languages? Why is there barely any Java documentation, support or examples? Or even (god forbid) a SharePoint Java library with some helper classes? I bet it would certainly attract new segments and stimulate the usage of SharePoint (or SharePoint Online) in heterogeneous IT ecosystems, what I’ve often seen in smaller companies… That would be a win-win situation for Microsoft and its customers in my opinion.

SharePoint Java Application screenshot

Tutorial introduction

In this post I will show a way to insert, update and delete SharePoint list items from Java. In case you want to build such an app from scratch, I invite you to read the three first steps of my previous tutorial that describe how to generate the Lists Web Service stub classes and how to authenticate to the Web Service. As usual, I’ve tested it with NetBeans and SharePoint Online, but it should work with MOSS 2007 and other Java IDEs. Please keep in mind that this is my take at Java and SharePoint and that there might be more efficient ways to do it, but hey, it works for me!

The challenge here will be to create a Lists request “wrapper” that will be able to do construct a basic CAML query skeleton. To better understand the structure of the request, the first stop is of course MSDN’s UpdateListItems doc. The problem is that MSDN often points fractions of the required CAML structure in their examples, but that’s not always enough, as we need to have a full SOAP sample for our Java app. What I found to be the most helpful was to fire up my browser and go to the URL of my Web Service method I was interested in. In this case, it will be UpdateListsItem, that can usually be found at sharepointsite/Lists/_vti_bin/Lists.asmx?op=UpdateListItems.

Tutorial: Creating list items from Java

In a hurry? You can download the full source code of what’s been covered until now here (GPLv2 license). Enjoy!

Here we go:

  1. Code the Lists request wrapper class. Basically this class will contain the XML SOAP request with the correct structure for the Lists Web Service. I included the imports below to avoid any ambiguity when fixing imports.
    import java.util.HashMap;
    import java.util.Map;
    import javax.xml.parsers.DocumentBuilder;
    import javax.xml.parsers.DocumentBuilderFactory;
    import javax.xml.parsers.ParserConfigurationException;
    import org.w3c.dom.Document;
    import org.w3c.dom.Element;
    import org.w3c.dom.Text;
    
    /**
     *   @author David Dudok de Wit
     *   @version 13 Feb. 2010
     */
    public class ListsRequest {
    
        private Document rootDocument;
        private Element rootDocContent;
    
        /**
         * @return the rootDocument
         */
        public Document getRootDocument() {
            return rootDocument;
        }
    
        /**
         * @return the rootDocContent
         */
        public Element getRootDocContent() {
            return rootDocContent;
        }
    }
    
    

     

  2. Code the ListsRequest constructor. This will construct a generic “New”, “Update” or “Delete” CAML request. In order to avoid errors I’ve added some requestType control checks. Moreover, to keep the constructor signature simple, I made it initialize less relevant parameters automatically (like try to insert each item of the batch operation, even if one fails).
        /**
         * This class creates a generic XML SOAP request pre-formatted for SharePoint
         * Lists web services requests (aka CAML query). What remains to be added are
         * the specific parameters (XML Elements with attributes).
         * For an example of a CAML Doc http://msdn.microsoft.com/en-us/library/lists.lists.updatelistitems.aspx
         * @param requestType Either New, Update or Delete
         * @throws Exception
         */
        public ListsRequest(String requestType) throws Exception {
            if (requestType != null) {
                if (requestType.equals("New") || requestType.equals("Update") || requestType.equals("Delete")) {
                    try {
                        Element rootElement = null;
                        DocumentBuilder docBuilder = null;
                        DocumentBuilderFactory dbfac = DocumentBuilderFactory.newInstance();
                        docBuilder = dbfac.newDocumentBuilder();
                        rootDocument = docBuilder.newDocument();
    
                        //Creates the root element
                        rootElement = rootDocument.createElement("Batch");
                        rootDocument.appendChild(rootElement);
    
                        //Creates the batch attributes
                        rootElement.setAttribute("ListVersion", "1");
                        rootElement.setAttribute("OnError", "Continue");
                        rootDocContent = rootDocument.createElement("Method");
                        rootDocContent.setAttribute("Cmd", requestType);
                        rootDocContent.setAttribute("ID", "1");
                        rootDocument.getElementsByTagName("Batch").item(0).appendChild(rootDocContent);
                    } catch (ParserConfigurationException ex) {
                        ex.printStackTrace();
                        throw (new Exception(ex.toString()));
                    }
                } else {
                    String err = "Unsupported request type";
                    throw (new Exception(err));
                }
            } else {
                String err = "Null parameters";
                throw (new Exception(err));
            }
        }
    
  3. Code the createListItem function. This function will inject a HashMap of attributes and their values into the ListsRequest CAML query, under an XML syntax.
        /**
         * Creates a SharePoint list item in the CAML format, and adds it to the rootRequest.
         * In SharePoint, this corresponds to a line in a list. The parameters given
         * here would correspond respectively to the name of the column where to
         * insert the info, and then the info itself.
         * The requestTypeElement should already be initialized before calling this
         * method.
         * XML example output:
         * < Field Name="ID" >4< Field >
         * < Field Name="Field_Name" >Value< /Field >
         * @param fields Contains a HashMap with attribute names as keys, and attributes
         * values as content
         * @return true if the item has been successfully added to the caml request
         */
        public boolean createListItem(HashMap<String, String> fields) {
            //params check
            if (fields != null && getRootDocContent() != null && this.getRootDocument() != null && !fields.isEmpty()) {
                Element createdElement = null;
                //Adds attribute by attribute to fields
                for (Map.Entry<String, String> aField : fields.entrySet()) {
                    createdElement = this.getRootDocument().createElement("Field");
                    createdElement.setAttribute("Name", aField.getKey());
                    Text attributeValue = getRootDocument().createTextNode("" + aField.getValue());
                    createdElement.appendChild(attributeValue);
                    this.getRootDocContent().appendChild(createdElement);
                }
                return true;
            }
            return false;
        }
    

     

  4. Code a higher level manager function. That’s from where we’ll authenticate, as well as decipher the error messages, and more importantly apply the business logic. This can be added in the Manager.java file. The example below is pretty basic doesn’t do basic existence checks, which means that the item will be inserted regardless if there’s already an item with the same attributes. It will however print the request in the console for debugging purposes (see the step 4 of my previous tutorial for the xmlToString function).
        /**
         * This function will insert the given item in the SharePoint that corresponds
         * to the list name given (or list GUID).
         * @param port an already authentificated SharePoint SOAP port
         * @param listName SharePoint list name or list GUID (guid must be enclosed in braces)
         * @param itemAttributes This represents the content of the item that need to be inserted.
         * The key represents the type of attribute (SharePoint column name) and the
         * value corresponds to the item attribute value.
         */
        public static void insertListItem(ListsSoap port, String listName, HashMap<String, String> itemAttributes) {
    
            //Parameters validity check
            if (port != null && listName != null && itemAttributes != null && !itemAttributes.isEmpty()) {
                try {
    
                    //Building the CAML query with one item to add, and printing request
                    ListsRequest newCompanyRequest = new ListsRequest("New");
                    newCompanyRequest.createListItem(itemAttributes);
                    System.out.println("REQUEST:"
                            + xmlToString(newCompanyRequest.getRootDocument()));
    
                    //initializing the Web Service operation here
                    Updates updates = new UpdateListItems.Updates();
    
                    //Preparing the request for the update
                    Object docObj = (Object) newCompanyRequest.getRootDocument().getDocumentElement();
                    updates.getContent().add(0, docObj);
    
                    //Sending the insert request to the Lists.UpdateListItems Web Service
                    UpdateListItemsResult result = port.updateListItems(listName, updates);
    
                    /*
                     *Printing the response in the console.
                     *If successful, the inserted item will be returned
                     */
                    System.out.println("RESPONSE : "
                            + xmlToString((org.w3c.dom.Document) (((ElementNSImpl) result.getContent().get(0)).getOwnerDocument())));
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }
    

     

  5. Testing the code. Just put a few lines in main to test the whole thing. Note that if you have a column name that contains a space, you’ll have to replace the space character with _x0020_ in your attributes.
                 //Authentication parameters
                String userName = "yourusername";
                String password = "yourpassword";
                String sharePointListsWebServiceUrl = "https://yoursharepointsite.com/_vti_bin/Lists.asmx";
    
                //Opening the SOAP port of the Lists Web Service
                ListsSoap port = Manager.sharePointListsAuth(userName, password, sharePointListsWebServiceUrl);
    
                //Name or GUID (with braces) of the list
                String listName = "TempList";
    
               //Create the attributes with the format "Column name" => "value"
                HashMap<String, String> item = new HashMap<String,String>();
                item.put("Title", "Michael Drummond");
                item.put("Address", "USA");
    
                //If your column name has a space in it, replace the space with _x0020_
                item.put("Premium_x0020_customer", "1");
                Manager.insertListItem(port, listName, item);
    
  6. Updating or deleting an item is very similar; you just have to specify the “ID” of the List item (which can be extracted by reading the list first), just like we did in the previous step with the attributes.

 

That’s it!
Keep in mind that this is a simple example that’s not guaranteed to be appropriate for a production environment. For example, It would be interesting to tweak the code to do allow batch inserts/deletes as well as a transaction system that would be able to cache the requests in case of failure. I hope you found this post helpful.

SharePoint Web Services: 3 things to consider before coding in Java

February 3, 2010 1 comment

Before starting the adventure of coding an application in Java for SharePoint Online, make sure you’re well prepared for the following points:

  • Documentation is rare. No code examples exist on MSDN other than for C# or VB.NET (and some SOAP signatures). Moreover, translating MSDN’s C# examples into Java is tough, as they use language specific imports. The best info I could find was a webcast with a java coding demo for SharePoint (in French: MSDN Webcast by Stève Sfartz). The SharePoint Online Developer Guide and the MSDN documentation will be your best friends though.
  • Microsoft’s WSDLs won’t generate easy to use POJOs. This is essentially because SharePoint Online’s SOAP Web Services are resource-orientated. This means you can send big and complex requests to SharePoint’s Web Services, but also that you’ll have to manipulate your objects like XML documents rather than objects. And the “XAML” structure used in the requests/responses isn’t always fully documented with examples on MSDN either.
  • Consuming SharePoint Online’s WSDLs in your favorite Java IDE won’t necessarily work. I had to use the Axis 1.4 from the command line to generate my Java classes for Netbeans (the generated classes couldn’t be compiled when imported from Netbeans wizard). Your mileage may vary…

Therefore, if you have the possibility to use C# instead of Java, don’t think twice: use C#. You’ll save a lot of development and maintenance time. I wouldn’t recommend developing an application in Java if its size goes beyond the one of a small application or proof-of-concept.