Below you can find sample code which shows how to use the Haystack PHP SDK

The Haystack SDK consists of three main files

• HaystackWebServiceClient.php - it is the main file in the SDK. Implements a PHP class which allow you to easily connect to the Web Service and make variour requests.
• XMLParser.php - A simple PHP XML parser used by the HaystackWebServiceClient class to parse the responses received from the Web Service and present them to the user in more PHP like format.
• hwsapi.php - A file with symbolic constants. Needed because it assigns human readable names to various numeric constants (like error codes).

Below follows a step by step example how to use the SDK in different scenarios. It is most convinient to read the document section after section because it is a sort of a scenario which tries to perform the following steps:

Required Includes
Creating a Haystack API Object
Creating New Haystack.
Getting a Haystack Id
Adding Profiles to the Haystack.
Adding Haystack Categories
Modifying Tag Values
Listing Profiles in a Haystack
Deleting Profiles
Deleting Haystacks

Content

Required Includes

Before using the API you need to add the following code to your PHP file

        require_once('HaystackWebServiceClient.php');
        
        // Some defines to help us with authentication
        define('MY_TOKEN', '2af334aa72e106f95a778f515c162aa3');
        define('MY_EMAIL', 'my.email@myorg.com');       // end 

You need to replace the MY_TOKEN and MY_EMAIL with the ones which are right for your authentication.

Creating a Haystack API Object

Using the Haystack Web Service is pretty easy with the supplied SDK. You just instantiate an object of type HaystackWebServiceClient and you are ready to call web methods in your PHP script.

        // Instantiating an API object.
        $apiClient = &new HaystackWebServiceClient(MY_TOKEN, MY_EMAIL); // end

Note:

This version of the SDK allows only synchroniuos method calls. This means that once you issue a web call the method will not return until the response is received.

Creating New Haystack.

Creating a new haystack is easy. Just use the HaystackWebServiceClient::HaystackCreate() method.

        $haystackName = 'myFavouriteHaystack';
        $apiClient->HaystackCreate($haystackName, $hid); // end

As a result of this command we receive in the $hid variable the ID of the created haystack. Below you will see how we use this $hid in order to manipulate the haystack.

Getting a Haystack Id

Sometimes you might not want to create a new haystack, but you would like to manipulate and existing haystack. This is done using the HaystackWebServiceClient::HaystackId() method.

        // Retrieve the ID of already existing haystack.
        $apiClient->HaystackId($haystackName, $hid2);
        
        // Validate that it is the same as the ID returned by the HaystackCreate() command. 
        assert($hid == $hid2); // end

Adding Profiles to the Haystack.

An empty haystack is good for nothing. You would like to add a few profiles to it in order to make it alive. Usually you would like to create new profiles for the members of your organization. But you can not only create new members but also add already existing in the system profiles to your haystack.

        // With this line of code we create a brand new profile in the system and assign
        // our haystack as its main haystack.
        $apiClient->ProfileCreate($hid, 'profile1@myorg.com', 'profile1_pass');
        
        // The next line creates another brand new profile but adds some additional info 
        // for the profile.
        $info = array('fname'=>'John', 'lname'=>'Smith');
        $apiClient->ProfileCreate($hid, 'john.smith@myorg.com', 'john_pass', $info);
        
        // And this last line does not create a new profile but add existing profile
        // to our haystack since 'ccarfi@cerado.com' already exists in the system.
        $apiClient->ProfileCreate($hid, 'stanimir.peev@sciant.com', ''); // end

For more details have a look at the HaystackWebServiceClient::ProfileCreate() method.

Adding Haystack Categories

The haystack categories are modified with the HaystackWebServiceClient::HaystackCategories() command. When you create a new haystack you already have a list of 12 categories.

        // First demonstrate that a newly created haystack already have categories in it.
        $apiClient->HaystackCategories($hid, $result);
        assert(count($result) > 0);
        
        // You can print the categories like this
        print_r($result);
        
        // Or you walk over the array of categories
        foreach ($result as $category)
        {
                echo $category;
        } // end

Of course you can easily add new commands. Just replace the value of the $subCmd parameter with 'add' instead of the default 'list' value.

        // Adding a new category is easy. With the code below you add a single category.
        $apiClient->HaystackCategories($hid, $result, 'add', 'myCategory1');
        
        // And with the code below you add a few categories at once.
        $apiClient->HaystackCategories($hid, $result, 'add', 
                        'myCategory2,myCategory3,myCategory4'); // end

Modifying Tag Values

Tags are in the heart of the Cerado Haystack system. You can easily add and remove tags using the Web Service API. Tag modification is not possible. If you need to modify a tag value you need to delete it and add a new value on its place.

        // Add the tag 'Sciant' to all profiles in our haystack.
        $apiClient->HaystackTags($hid, $result, 'add', 'Organization', 'Sciant');
        
        // Now add the 'Wizcom' tag under the 'Organization' category for two
        // specific profiles.
        $apiClient->HaystackTags($hid, $result, 'add', 'Organization', 'Wizcom', 
                        'stanimir.peev@sciant.com, john.smith@myorg.com'); // end

See also:

HaystackWebServiceClient::HaystackTags() command.

Listing Profiles in a Haystack

This functionality roughly corresponds to the 'View All' page in the Haystack Web UI. For detailed info of all supported variants of this command you should look at the documentation. Below are some examples how you would retrieve a particular set of profiles.

        // First list all profiles which have the 'Sciant' tag in the 'Otganization'
        // category.
        $apiClient->HaystackListProfiles($hid, $result, 'Organization', 'Sciant');
        
        // Since we added this tag to all profiles we should assert that the number returned 
        // is equal to 4.
        assert(count($result) == 4);
        
        // Then for each profile print its first and last name
        foreach( $result as &$profile )
        {
                echo $profile['fname'], ' ', $profile['lname'];
        }
        
        // Now list all profiles which have a tag 'Wizcom' (regardless of the category), but 
        // take only their e-mail as return value.
        $apiClient->HaystackListProfiles($hid, $result, null, 'Wizcom', 1, 'email'); // end

See also:

HaystackWebServiceClient::HaystackListProfiles()

Playing with a Profile Network

You can modify a profile network. There are three main commands for this purpose: HaystackWebServiceClient::MyNetworkAdd(), HaystackWebServiceClient::MyNetworkDel() and HaystackWebServiceClient::MyNetworkList()

        // First try to receive a list of profiles in a pesons's network.
        $user1 = 'john.smith@myorg.com';
        $apiClient->MyNetworkList($user1, $network);
        // But since we haven't added any, the result should be empty.
        assert(count($network) == 0);
        
        // Now add two persons in the network of 'john.smith@myorg.com'.
        $apiClient->MyNetworkAdd($user1, 'profile1@myorg.com, stanimir.peev@sciant.com');
        $apiClient->MyNetworkList($user1, $network);
        // Now we should have more profiles.
        assert(count($result) == 2);
        
        // Delete one of the users in $user1 network. This will remove
        // the profile from 'john.smith@myorg.com' network, but the profile
        // itself will contonue to exists in the system.
        $apiClient->MyNetworkDel($user1, 'profile1@myorg.com'); // end

Deleting Profiles

We can delete profiles from a haystack. Actually we can delete profiles only from haystacks which we administer. Below is an example how to do this

        // With this call we delete the 'profile1@myorg.com' from the 'myFavouriteHaystack'
        // haystack. Since this is the profile's one and only haystack, the profile is
        // wiped out of the system.
        $apiClient->ProfileDelete($hid, 'profile1@myorg.com');
        
        // The following code delete a profile which belongs to multiple haytacks.
        // As a result the profile is removed from 'myFavouriteHaystack' but continues to
        // stay in the system.
        $apiClient->ProfileDelete($hid, 'stanimir.peev@sciant.com'); // end

See also:

HaystackWebServiceClient::ProfileDelete()

Deleting Haystacks

Deleting whole haystacks is as easy as deleting profiles.

        // This code deletes the haystack we created.
        $apiClient->HaystackDelete($hid) // end

See also:

HaystackWebServiceClient::HaystackDelete()

---