Chart service
Warning
Before you begin set the Access API Key as described in Getting started
With the chart service you can:
- Add employee/s
- Update employee
- Remove employee
- Get employee/s
- Search
- Create/Update/Remove/List org charts
- Generate employee ids
Add employee/s
Before adding emplyees to the chart, first you will need to create an empty chart
var chartService = new ChartService();
var options = new OptionsCreateNewChart
{
ChartId = "AddEmployees",
TemplateName = "Sofia",
Empty = true
};
var resultCreate = chartService.Create(options);
When the chart is created you can add new employee
var optionsAddNode = new OptionsAddNode
{
ChartId = "AddEmployees",
Node = new Dictionary<string, string>
{
{ "id", "1" },
{ "Name", "John Smith" }
}
};
var resultAddNode = chartService.AddNode(optionsAddNode);
The first option parameter is the chart id and the second is the employees name.
Important
As you can see the method is named AddNode instead of AddEmployee and to the rest of the documentation we will refer to a node instead of employee because the api can be used in different contexts, for example family tree or other tree like structure
Now check if the operation is successful
if (!resultAddNode.IsSuccess)
{
Console.WriteLine(resultAddNode.Error);
}
The result object has the following fields:
- IsSuccess - determines if the operation is successful
- Error - The error message if any
- ExecutionTime - Server execution time in miliseconds
Next you can add a node that reports to the first one
optionsAddNode = new OptionsAddNode
{
ChartId = "AddEmployees",
Node = new Dictionary<string, string>
{
{ "id", "2" },
{ "pid", "1" },
{ "Name", "Jack Daniels" }
}
};
resultAddNode = chartService.AddNode(optionsAddNode);
The pid field specifies that node with id "2" reports to node with id "1"
The next code demostrates how to add assistant node highlighted in blue
optionsAddNode = new OptionsAddNode
{
ChartId = "AddEmployees",
Node = new Dictionary<string, string>
{
{ "id", "3" },
{ "pid", "1" },
{ "Name", "Mickey Mouse" },
{ "tags", "blue,assistant" }
}
};
resultAddNode = chartService.AddNode(optionsAddNode);
The tags field determines that the node is assistant with blue color
Finaly add node with an image and more fields
optionsAddNode = new OptionsAddNode
{
ChartId = "AddEmployees",
Node = new Dictionary<string, string>
{
{ "id", "4" },
{ "pid", "1" },
{ "Name", "Ana Garson" },
{ "Photo", "https://cdn.balkan.app/shared/2.jpg" },
{ "Country", "USA" },
{ "City", "Las Vegas" },
{ "JobTitle", "IT Manager" },
{ "Email", "ana.garson@balkan.app" }
}
};
resultAddNode = chartService.AddNode(optionsAddNode);
Here is the full code
public static void AddEmployees()
{
var chartService = new ChartService();
var options = new OptionsCreateNewChart
{
ChartId = "AddEmployees",
TemplateName = "Sofia",
Empty = true
};
var resultCreate = chartService.Create(options);
if (!resultCreate.IsSuccess)
{
Console.WriteLine(resultCreate.Error);
}
var optionsAddNode = new OptionsAddNode
{
ChartId = "AddEmployees",
Node = new Dictionary<string, string>
{
{ "id", "1" },
{ "Name", "John Smith" }
}
};
var resultAddNode = chartService.AddNode(optionsAddNode);
if (!resultAddNode.IsSuccess)
{
Console.WriteLine(resultAddNode.Error);
}
optionsAddNode = new OptionsAddNode
{
ChartId = "AddEmployees",
Node = new Dictionary<string, string>
{
{ "id", "2" },
{ "pid", "1" },
{ "Name", "Jack Daniels" }
}
};
resultAddNode = chartService.AddNode(optionsAddNode);
if (!resultAddNode.IsSuccess)
{
Console.WriteLine(resultAddNode.Error);
}
optionsAddNode = new OptionsAddNode
{
ChartId = "AddEmployees",
Node = new Dictionary<string, string>
{
{ "id", "3" },
{ "pid", "1" },
{ "Name", "Mickey Mouse" },
{ "tags", "blue,assistant" }
}
};
resultAddNode = chartService.AddNode(optionsAddNode);
if (!resultAddNode.IsSuccess)
{
Console.WriteLine(resultAddNode.Error);
}
optionsAddNode = new OptionsAddNode
{
ChartId = "AddEmployees",
Node = new Dictionary<string, string>
{
{ "id", "4" },
{ "pid", "1" },
{ "Name", "Ana Garson" },
{ "Photo", "https://cdn.balkan.app/shared/2.jpg" },
{ "Country", "USA" },
{ "City", "Las Vegas" },
{ "JobTitle", "IT Manager" },
{ "Email", "ana.garson@balkan.app" }
}
};
resultAddNode = chartService.AddNode(optionsAddNode);
if (!resultAddNode.IsSuccess)
{
Console.WriteLine(resultAddNode.Error);
}
}
Here is the chart you just created
There are 3 types of fields you can add to a node
System fields:
- id: (Mandatory) has to be unique for a chart
- pid: (Optional) parent id
- tags: (Optional) comma separated tags
- stpid: (Optional) sub tree parent id
- ppid: (Optional) parent partner id
Translated fields: - translated in 110 languages
- Name
- JobTitle
- Photo
- Address
- MobilePhone
- HomePhone
- HomeAddress
- PersonalEmail
- Department
- Salary
- Notes
Your own fields:
- MyFieldName
- FieldInMyLanguage
You can define your fields in your language and they will display in the node details window. The key and the value can be maximum 256 chartcters and max 50 fields per node are alowed in a node.
To simplify the code above you can use AddNodes instead of calling AddNode multiple times
public static void AddNodes()
{
var chartService = new ChartService();
var resultAddNodes = chartService.AddNodes(new OptionsAddNodes
{
ChartId= "AddNodesChartName",
Nodes = new List<Dictionary<string, string>>
{
new Dictionary<string, string> { { "id", "1" }, { "Name", "John Smith" } } ,
new Dictionary<string, string> { { "id", "2" }, { "pid", "1" }, { "Name", "Jack Daniels" } },
new Dictionary<string, string> { { "id", "3" }, { "pid", "1" }, { "Name", "Mickey Mouse" }, { "tags", "blue,assistant" }},
new Dictionary<string, string> { { "id", "4" }, { "pid", "1" }, { "Name", "Ana Garson" }, { "Photo", "https://cdn.balkan.app/shared/2.jpg" },{ "Country", "USA" },{ "City", "Las Vegas" },{ "JobTitle", "IT Manager" },{ "Email", "ana.garson@balkan.app" }}
}
});
if (!resultAddNodes.IsSuccess)
{
Console.WriteLine(resultAddNodes.Error);
}
}
If the chart does not exist the system will create a chart with id "AddNodesChartName" with deafult template Sofia
Update node (employee)
Add "CreateTestChart" util method, CreateTestChart creates a new chart.
public static void CreateTestChart(string chartId)
{
var chartService = new ChartService();
chartService.Create(new OptionsCreateNewChart
{
ChartId = chartId,
TemplateName = "Berlin"
});
}
To update specific node you can
public static void UpdateNode()
{
CreateTestChart("UpdateNodeChart");
var chartService = new ChartService();
var resultUpdateNode = chartService.UpdateNode(new OptionsUpdateNode
{
ChartId = "UpdateNodeChart",
Node = new Dictionary<string, string>
{
{ "id", "_sfWf" },
{ "Name", "Alexandar Smith" },
{ "JobTitle", "CEO" }
}
});
if (!resultUpdateNode.IsSuccess)
{
Console.WriteLine(resultUpdateNode.Error);
}
}
The code above will update the name of a node with id "_sfWf" in chart "UpdateNodeChart" and will add new field JobTitle or it will return an error if the node or chart does not exists
Remove node (employee)
The following code will remove a node with id "_s7Wf" in chart "RemoveNodeChart" or it will return an error if does not exist
public static void RemoveNode()
{
CreateTestChart("RemoveNodeChart");
var chartService = new ChartService();
var resultRemoveNode = chartService.RemoveNode(new OptionsRemoveNode
{
ChartId = "RemoveNodeChart",
NodeId = "_s7Wf"
});
if (!resultRemoveNode.IsSuccess)
{
Console.WriteLine(resultRemoveNode.Error);
}
}
if the node "_s7Wf" has children you can specify new parent ids for that children using NewPidsForIds option and/or NewStpidsForIds
Get node/s (employee/s)
Get node by node id and chart id
public static void GetNode()
{
CreateTestChart("GetNodeChart");
var chartService = new ChartService();
var resultGetNode = chartService.GetNode(new OptionsGetNode
{
ChartId = "GetNodeChart",
NodeId = "_s7Wf"
});
if (!resultGetNode.IsSuccess)
{
Console.WriteLine(resultGetNode.Error);
}
}
Get nodes by chart id
public static void GetNodes()
{
CreateTestChart("GetNodesChart");
var chartService = new ChartService();
var resultGetNodes = chartService.GetNodes(new OptionsChart
{
ChartId = "GetNodesChart"
});
if (!resultGetNodes.IsSuccess)
{
Console.WriteLine(resultGetNodes.Error);
}
}
Search functionallity
There are two types of search, client side and server side. The client side search is on the top right corner and it search only in the current chart. The algorithm for both is almost identical.
Here is an example how to search for a node with field "Name" that contains letter "J" and second name "Smith"
public static void Search()
{
CreateTestChart("SearchChart");
var chartService = new ChartService();
var optionsSearch = new OptionsSearch
{
RetrieveFields = new List<string> { "Name", "JobTitle", "MyPropertyName" },
Skip = 1,
Take = 100,
Search = "So Ed",
SearchInFileds = new List<string> { "Name" }
};
var resultListAllNodes = chartService.Search(optionsSearch);
if (!resultListAllNodes.IsSuccess)
{
Console.WriteLine(resultListAllNodes.Error);
}
else
{
foreach (var node in resultListAllNodes.Nodes)
{
Console.WriteLine($"node.id = {node["id"]}");
Console.WriteLine($"node.__chartId = {node["__chartId"]}");
Console.WriteLine($"node.__searchField = {node["__searchField"]}");
Console.WriteLine($"node.__searchMarks = {node["__searchMarks"]}");
Console.WriteLine($"node.__score = {node["__score"]}");
if (node.ContainsKey("Name"))
Console.WriteLine($"node.Name = {node["Name"]}");
if (node.ContainsKey("JobTitle"))
Console.WriteLine($"node.JobTitle = {node["JobTitle"]}");
if (node.ContainsKey("MyPropertyName"))
Console.WriteLine($"node.MyPropertyName = {node["MyPropertyName"]}");
}
}
}
Visual result:
The search result will return a collection of nodes with the following fields:
- Name: if the node has Name field
- JobTitle: if the node has JobTitle field
- MyFieldName: if the node has MyFieldName field
- id: the id of the node
- __chartId: the chart id
- __searchField: One of the elements you defined in SearchInFileds option. For example if "J Smith" is found inthe Name field the value will be Name
- __score: The score of the seach in percents. Zero if is the minimum one hundred maximum. One hundred means that there is one hendred match, for example if you seach for "John" and there is a field "John" the score will be 100
- __searchMarks: html text result surrounded by mark html tags
You can order, sort and filter by the fields above
The code will return a list of 100 maches (if exist) skipping the first one. Skip and Take are usefull for paging
Create/Update/Remove/List charts
Create, Update, List and Remove
public static void CreateUpdateRemoveList()
{
var chartService = new ChartService();
var optionsCreateNewChart = new OptionsCreateNewChart
{
ChartId = "CreateUpdateRemoveListChart",
TemplateName = "Berlin"
};
var resultChart = chartService.Create(optionsCreateNewChart);
if (!resultChart.IsSuccess)
{
Console.WriteLine(resultChart.Error);
}
var optionsUpdateChart = new OptionsUpdateChart
{
NewChartId = "CreateUpdateRemoveListChartNewUpdated",
NewTemplateName = "London",
OldChartId = "CreateUpdateRemoveListChart"
};
resultChart = chartService.Update(optionsUpdateChart);
if (!resultChart.IsSuccess)
{
Console.WriteLine(resultChart.Error);
}
var optionsList = new OptionsList
{
Skip = 0,
Take = 10,
WildcardSearchPattern = "*NewUpdated*"
};
var resultList = chartService.ListDescriptors(optionsList);
if (!resultList.IsSuccess)
{
Console.WriteLine(resultList.Error);
}
var optionsChart = new OptionsChart
{
ChartId = "CreateUpdateRemoveListChartNewUpdated"
};
var resultRemove = chartService.Remove(optionsChart);
if (!resultRemove.IsSuccess)
{
Console.WriteLine(resultRemove.Error);
}
}
If you want to delete all charts call "Empty" method
Generate node ids
In some cases you may want to generate unique node id before adding a node to a chart
public static void GenerateNodeIds()
{
CreateTestChart("GenerateNodeIdsChart");
var chartService = new ChartService();
var optionsGenerateNodeIds = new OptionsGenerateNodeIds
{
ChartId = "GenerateNodeIdsChart",
Number = 10
};
var resultGenerateNodeIds = chartService.GenerateNodeIds(optionsGenerateNodeIds);
if (!resultGenerateNodeIds.IsSuccess)
{
Console.WriteLine(resultGenerateNodeIds.Error);
}
else
{
foreach (var id in resultGenerateNodeIds.Ids)
{
Console.WriteLine(id);
}
}
}
Note
The demo is located at GitHub