SDK Developer Documentation

Developer Documentation Describing the Viewpoint for ProjectsSDK

Index

Overview

Platform

4Projects SDK

4Projects Examples

Configuration

Authenticating

General SDK Class CRUD Patterns

Querying Data

Overview

The 4Projects SDK wraps up some common functionality for the 4Projects API services. The SDK may be used to integrate with your own applications and systems. This document describes the SDK and the SDK Examples which will help you to get started and become familiar.

Platform

The examples given here were written in C# using Visual Studio 2008 targeting the .NET 3.5 Framework.

4Projects SDK

The 4Projects API services may be consumed by using the SDK. The file is contained in this SDK called FourProjectsAPI.dll and can be added as a reference to Visual Studio projects.

Classes

Each service entity has its own class prefixed with ‘Sdk’. Non service entities at the time of writing are SdkUtilities, SdkResult and SdkFileTransfer.

Within the Public Methods region you will find the methods that you may wish to use, such as SdkPersonalContainer.Add or SdkSite.Delete.

4Projects Examples

The SDK Examples use the SDK to demonstrate how to use the 4Projects services. The Visual Studio Console Application project called FourProjectsAPIExamples contains the source code.

Program Class

The main program is ran from Program.Main class. This contains the actual example method calls.Some are deliberately commented out so you can select which ones to use. To get started please note the following:

  1. Ensure the private variables Password, Secret Key and UserName etc are completed with your 4Projects 3G credentials. These are located at the top of the Program.cs class in the FourProjectsAPIExamples. If you do not have an App ID yet then please contact 4Projects to request one.

//NOTE: Modify these values for your own Username, Password, Secret Key,App ID, EnterpriseID and User ID before running these examples

public static string UserName { get { return"Your User Name"; } };

public static stringPassword { get { return"Your Password"; } };

public static stringSecretKey { get { return"Your Secret Key"; } };

public static stringAppID { get { return"Your App ID"; } };

// A valid Enterprise ID is required for all tests except the personal container tests

public static stringDefaultEnterpriseId { get { return"Your Enterprise ID"; } };

// A user ID is used for assignments in task examples and recipients in discussions

public static string UserId { get { return"Your User ID"; } };

  1. Ensure the DefaultEnterpriseId references the Enterprise in 3G you wish to use in the examples. To establish this,
  2. Log in to 3G
  3. Right click on the Enterprise you wish to use and choose Configure, This Container from the menu.
  4. Right click on the window to bring up the Properties Window and use the cursor to highlight and scroll on the Address to reveal the GUID of the Enterprise specified as containerguid=<yourEnterpriseGUID> within the URL text. See the screenshot below but note that the full GUID is not shown in the examples so ensure you do have the full GUID. You may wish to copy it to the clipboard and inspect it in Notepad.
  1. Ensure the UserID references your UserID in 3G. To establish this,
  2. Log in to 3G
  3. Choose Personalise, User Details from the menu.
  4. In the same way as the step above, right click on the window to bring up the Properties Window and use the cursor to highlight and scroll on the Address to reveal the GUID of the User specified as objectid=<yourUserGUID> within the URL text.
Example Classes

Each example has a class suffixed with the word ‘Example’. There are several methods within the classes which will work with the services. Some are deliberately commented out. The main example to look at in each of the example classes is the CreateRetrieveUpdateDelete() which will show the basic code to implement CRUD operations on the SDK classes. Other examples could be useful but may require you to enter appropriate GUIDs into the code for them to run.

Always run the examples against a development environment rather than live to avoid creating data in the live environment.

Configuration

There is a configuration file for the FourProjectsAPIExamples assembly which contains all of the configuration required for the SDK classes to utilize the API. You will need to copy the configuration from this file to your own application’s config file to utilize the SDK classes.

The assembly file has 2 important settings at the top:

UseEndpointsFromConfigFile – default is True. If set to false then the SDK classes will use hardcoded values for the binding behavior etc which may be required if you are using the class from somewhere that it is difficult to have a config file, for instance a plugin that can be used in multiple applications etc. This gives you much less control over the client configuration than using a configuration file.

BaseURI – This is the base URI used when UseEndpointsFromConfigFile is set to false – most people will not require this to change.

Authenticating

To call any of the services you will require a token. This can be acquired with the following call:

// Acquire a token

string token = SdkAuthentication.GetToken(_userName, _password, _secretKey, newGuid(_appID));

General SDK Class CRUD Patterns

Usage of the SDK classes generally follows these patterns:

  1. To create a new object, pass in the id of the parent to the constructor and set the ID type as being a parent. This will populate things like Custom Fields, Keywords, Workflows etc for the context. If you know you are not using these types of functionality then you could use the default constructor and just set the parent ID before saving. For example to create a new site:

// Get a new site passing in the enterprise we want to create the site in

SdkSite Site = newSdkSite(EnterpriseID, SdkSite.IDType.NewSiteParent, Token);

// Now set the values on the site

Site.Name = "Some Name";

Site.Description = "Some Description";

// Now save the site

SdkResult result = Site.Save();

// Always check the result to ensure that it is successful

if(!result.Success)

{

Console.WriteLine("Updating a site was not successful: " + result.ID + " : " + result.Message);

}

  1. To retrieve an existing object just pass in the ID of the object and set the ID type to Existing. Objects with revisions or posts, such as documents, tasks, discussions etc, allow setting a retrieval type. This retrieval type can be used to retrieve just the item’s header information, the header information and the current revision or latest post, or the item header with all post or revision information. For example, to retrieve a task with all post info:

// Retrieve a task

SdkTaskTask = newSdkTask(taskID, SdkTask.IDType.ExistingTask, Token, RetrievalType.RetrieveParentAndAllChildrenInfo, null);

  1. After retrieving an item, you can update properties on it and save it. For example to update a project:

// Retrieve a project

SdkProjectProject = newSdkProject(projectID, SdkProject.IDType.ExistingProject, Token);

// Update values

Project.Description = "Updated Description";

Project.Name = "Updated Name";

// Save the project

SdkResultresult = Project.Save();

// Always check the result to ensure that it is successful

if (!result.Success)

{

Console.WriteLine("Updating a project was not successful: " + result.ID + " : " + result.Message);

}

  1. There are two ways to delete an item
  2. Call a static function on the SDK class, passing in a list of IDs that you want to delete, for example to delete 2 personal containers:

ListSdkResult> results = SdkPersonalContainer.DeletePersonalContainers(ListGuid

{ContainerID1, ContainerID2}, _token);

// Always check the results to ensure that it is successful

if (!results[0].Success)

{

Console.WriteLine("Deleting a personal container was not successful: " + result.ID + " : " + result.Message);

}

if (!results[1].Success)

{

Console.WriteLine("Deleting a personal container was not successful: " + result.ID + " : " + result.Message);

}

  1. Retrieve it then call delete on it, for example for a document container:

// Retrieve the document container from data and check the values have changed

SdkDocumentContainerDocumentContainer = new

SdkDocumentContainer(documentContainerID,

SdkDocumentContainer.IDType.ExistingDocContainer, Token);

// Delete the document container

SdkResultresult = DocumentContainer.Delete();

// Always check the result to ensure that it is successful

if (!result.Success)

{

Console.WriteLine("Deleting a personal container was not successful: " + result.ID + " : " + result.Message);

}

  1. To upload a file, for example to a document’s current revision:

// Add a file to the document revision and set it as the primary

SdkResultresult = document.AddFile(document.CurrentRevisionID,

@"../../App_Data/TestFiles/ToUpload/streamIn.txt", true);

// Always check the result to ensure that it is successful

if (!result.Success)

{

Console.WriteLine("Uploading a file was not successful: " + result.ID +

": " + result.Message);

}

  1. To download a file, for example from a personal container file:

// The location and name of the file as it will be saved locally

string targetPath = @"../../App_Data/TestFiles/Downloaded/Downloaded.txt";

// Get the personal container that the file is in

SdkPersonalContainer PersonalContainer = new

SdkPersonalContainer(personalContainerID, _token);

// Save the file locally

SdkResult result = PersonalContainer.GetFile(personalFileID, targetPath);

// Always check the result to ensure that it is successful

if (!result.Success)

{

Console.WriteLine("Downloading a file was not successful: " + result.ID +

": " + result.Message);

}

Querying Data

There are two ways to query the data using the SDK.

To get containers in the tree, use the RetrieveTree method passing in a context of the Container ID that you want to see the immediate child containers of. For example, to retrieve all the sites under an enterprise:

// Set the context to retrieve the immediate child containers of

Guid context = newGuid(EnterpriseID);

// Retrieve the sites

SdkResult result = SdkQueryList.RetrieveTree(context, Token);

// Always check the result to ensure that it is successful

if (result.Success)

{

// Get the result set

QueryListResponseInfo resultset =

(QueryListResponseInfo) result.ResultObject;

// Format the results to an XML string (can be JSON, XML or CSV)

stringXMLresults =SdkQueryList.ResponseToXML(resultset)

}

To retrieve items such as revisions, tasks etc use the Search method passing in a QueryListRequestInfo, for example, to retrieve the names, descriptions and IDs of documents in a document container (NOTE: See the accompanying API Developer Documentation to find out more about the search string and what make valid column names and where clauses etc):

// Create the query string

QueryListRequestInfo request = newQueryListRequestInfo {

SearchString = "select id, name, description from document",

SearchContext = DocumentContainerID,

RecursiveSearch = false,

LatestRevisionOnly = true

};

// Run the query

dkResult results = SdkQueryList.Search(request, Token);

// Always check the result to ensure that it is successful

if (result.Success)

{

// Get the result set

QueryListResponseInfo resultset =

(QueryListResponseInfo) result.ResultObject;

// Format the results to a JSON string (can be JSON, XML or CSV)

stringJSONresults =SdkQueryList.ResponseToJSON(resultset)

}