The Tab Manager API supports programmatically managing tabs in the Relativity. It includes the following features:
As a sample use case, you might use the Tab Manager service to add specialized tab functionality to custom pages in a Relativity application developed for your organization.
You can also use the Tab Manager service through the REST API. For more information, see Tab Manager (REST).
This page contains the following information:
Review the following information to learn about the methods, classes, and other entities used by the Tab Manager service. For reference information, see Services API.
In the Relativity Services API, the Relativity.Services.Interfaces.Tab namespace contains the ITabManager interface that exposes the following methods:
The Tab Manager API uses the following classes and enumerations available in the Relativity.Services.Interfaces.Tab.Models namespace:
NavigationTabResponse class - represents navigation information about a tab, including its URL as well as its name, order, visibility, parent and other properties. The GetAllNavigationTabs() method returns a list of objects of this type.
Review the following guidelines for working with the Tab Manager service.
You can access the Tab Manager service by creating a client proxy through the Relativity Services API, and then instantiating a TabManager object. See the following sample code:
Uri servicesUri = new Uri("http://localhost/relativity.services");
Uri keplerEndPoint = new Uri("http://localhost/relativity.rest/api");
Services.ServiceProxy.ServiceFactory serviceFactory = new Services.ServiceProxy.ServiceFactory(new Services.ServiceProxy.ServiceFactorySettings(servicesUri, keplerEndpoint,
new Services.ServiceProxy.UsernamePasswordCredentials("username", "password")));
Services.Interfaces.Tab.ITabManager proxy = serviceFactory.CreateProxy<Services.Interfaces.Tab.ITabManager>();
The methods on the Tab Manager API require that you pass an integer representing a workspace ID. You must pass -1 when you want to indicate the admin-level context. For example, you would pass -1 as the workspace ID to retrieve metadata for system or admin tabs. See Retrieve workspace-level metadata for admin and system tabs.
When you call a method on the Tab Manager API, it returns a Task object. You can retrieve the data returned in Task object by retrieving the awaiter for the Task object, and then calling the GetResult() method. See the following sample code:
List<TabViewOrder> tabViewOrder = tabManager.GetViewOrderList(WorkspaceID).GetAwaiter().GetResult(); List<NameIDPair> allParentTabs = tabManager.GetAvailableParentsAsync(WorkspaceID).GetAwaiter().GetResult(); TabResponse entitiesTabResponse = tabManager.ReadAsync(WorkspaceID, entitiesTabArtifactID).GetAwaiter().GetResult();
When creating a tab, you must the set the Parent property. This property is required for tabs at all levels, including tabs created at the admin-level or as parent tabs. For admin-level tabs, set this property to SystemArtifactId, as illustrated in the following code sample:
int systemArtifactID = artifactHelper.RetrieveSystemArtifactId();
return new TabRequest()
{
Name = Constants.ENTITIES_PARENT_TAB_NAME,
Order = newEntitiesParentTabOrder,
LinkType = TabLinkTypeEnum.Parent,
IsVisible = true,
Parent = new ObjectIdentifier { ArtifactID = systemArtifactID }
};
You may want to update a tab by using data obtained from a read operation. In the Tab Manager API, the ReadAsync() method returns a TabResponse object. However, the UpdateAsync() method requires that you pass a TabRequest object to it. To use data obtained from a read operation, you need to translate it from the form provided in the TabResponse object to that required for a TabRequest object, as illustrated in the following code sample:
TabResponse entitiesTabResponse = tabManager.ReadAsync(WorkspaceID, entitiesTabArtifactID).GetAwaiter().GetResult();
TabRequest entitiesTabRequest = TranslateTabResponseToTabRequest(entitiesTabResponse);
private TabRequest TranslateTabResponseToTabRequest(TabResponse tabResponse)
{
TabRequest tabRequest = null;
if (tabResponse != null)
{
tabRequest = new TabRequest
{
Name = tabResponse.Name,
Order = tabResponse.Order,
Link = tabResponse.Link,
IsDefault = tabResponse.IsDefault,
IsVisible = tabResponse.IsVisible,
RelativityApplications = tabResponse.RelativityApplications.ViewableItems.Select(x => new ObjectIdentifier { ArtifactID = x.ArtifactID }).ToList(),
LinkType = tabResponse.LinkType,
Parent = new ObjectIdentifier { ArtifactID = tabResponse.Parent.Value.ArtifactID },
ArtifactID = tabResponse.ArtifactID,
};
if ((tabResponse.ObjectType?.ArtifactID ?? -1) > 0)
{
tabRequest.ObjectType = new ObjectTypeIdentifier { ArtifactID = tabResponse.ObjectType.ArtifactID };
}
}
return tabRequest;
}
To create a tab, call the CreateAsync() method by passing the Artifact ID of the workspace and a TabRequest object to it, as illustrated in the following code sample:
public bool CreateAsync(IHelper helper)
{
bool success = false;
using (ITabManager proxy = helper.GetServicesManager().CreateProxy<ITabManager>(ExecutionIdentity.System))
{
try
{
string tabName = "Sample_Tab";
TabRequest request = new TabRequest
{
Name = tabName,
Order = 100,
LinkType = TabLinkTypeEnum.Object,
IsVisible = true,
Parent = new ObjectIdentifier { ArtifactID = 1003663 }
};
int artifactId = proxy.CreateAsync(SampleWorkspace_ID, request).GetAwaiter().GetResult();
if (artifactId != 0)
{
success = true;
}
else
{
_logger.LogError("Create failed");
}
}
catch (Exception ex)
{
_logger.LogError("Create failed - {message}", ex.Message);
throw;
}
}
return success;
The Tab Manager API includes the overloaded ReadAsync() method that you can use to retrieve basic or extended metadata for a tab. Extended metadata includes operations that you have permissions to perform on the tab, such as delete or update.
For basic tab metadata, call the ReadAsync() method by passing the Artifact IDs of the workspace and the tab. For extended metadata, you can pass Boolean values for both the includeMetadata and includeActions parameters on the overloaded method.
The following code sample illustrates how to retrieve basic metadata for a tab:
public bool ReadAsync(IHelper helper)
{
bool success = false;
using (ITabManager proxy = helper.GetServicesManager().CreateProxy<ITabManager>(ExecutionIdentity.System))
{
try
{
TabResponse response = proxy.ReadAsync(SampleWorkspace_ID, SampleTab_ID).GetAwaiter().GetResult();
_logger.LogDebug("{TabID} - {TabName}", response.ArtifactID, response.Name);
success = true;
}
catch (Exception ex)
{
_logger.LogError("Read failed - {message}", ex.Message);
throw;
}
}
return success;
}
To modify the properties of a tab, call the UpdateAsync() method by passing Artifact ID of the workspace and a TabRequest object to it. This overloaded method also supports restricting the update of a tab to the date that it was last modified. To restrict the update, you must pass a DateTime object to the method as well.
Note: The value for the DateTime object must match the LastModifiedOn date for the tab stored in Relativity. Otherwise, you receive an error, indicating that the object has been modified.
The following code sample illustrates how to update a tab:
public bool UpdateAsync(IHelper helper)
{
bool success = false;
using (ITabManager proxy = helper.GetServicesManager().CreateProxy<ITabManager>(ExecutionIdentity.System))
{
try
{
string tabName = "Sample_Tab";
TabRequest request = new TabRequest
{
Name = tabName,
Order = 100,
LinkType = TabLinkTypeEnum.Object,
IsVisible = true,
Parent = new ObjectIdentifier { ArtifactID = 1003663 },
ObjectType = new ObjectTypeIdentifier { ArtifactTypeID = 10 }
};
proxy.UpdateAsync(SampleWorkspace_ID, request).GetAwaiter().GetResult();
success = true;
}
catch (Exception ex)
{
_logger.LogError("Update failed - {message}", ex.Message);
throw;
}
}
return success;
}
The Tab Manager API includes the DeleteAsync() method for removing a tab from Relativity. You must have the permissions to perform a delete operation. For more information, see Security and permissions in the Relativity 9.6 Documentation site.
Before you delete a tab, consider checking for other dependent tabs. See Retrieve dependent objects.
The following code sample illustrates how to remove a tab by passing the Artifact IDs of the workspace and the existing tab to the DeleteAsync() method:
public bool DeleteAsync(IHelper helper)
{
bool success = false;
using (ITabManager proxy = helper.GetServicesManager().CreateProxy<ITabManager>(ExecutionIdentity.System))
{
try
{
proxy.DeleteAsync(SampleWorkspace_ID, SampleTab_ID).GetAwaiter().GetResult();
success = true;
}
catch (Exception ex)
{
_logger.LogError("Delete failed - {message}", ex.Message);
throw;
}
}
return success;
}
When creating or editing a tab, you must associate it with an object. In the Tab Manager API, you can use the overloaded GetAvailableObjectTypesAsync() method to obtain a list of available object types before executing these operations:
public bool GetAvailableObjectTypesAsync(IHelper helper)
{
bool success = false;
using (ITabManager proxy = helper.GetServicesManager().CreateProxy<ITabManager>(ExecutionIdentity.System))
{
try
{
List<NameIDPair> response = proxy.GetAvailableObjectTypesAsync(SampleWorkspace_ID).GetAwaiter().GetResult();
_logger.LogDebug("All availble object types for workspace {WorkspaceID}", SampleWorkspace_ID);
foreach (NameIDPair nameID in response)
{
_logger.LogDebug("{Name} - {ArtifactID}", nameID.Name, nameID.ID);
}
success = true;
}
catch (Exception ex)
{
_logger.LogError("Get all available object types failed - {message}", ex.Message);
throw;
}
}
return success;
}
In the Relativity UI, a parent tab displays a drop-down list containing child tabs. The Tab Manager service includes the GetAvailableParentsAsync() method that retrieves a list of parent tabs, which you can associate with a tab when you add or edit it. Pass this method the Artifact ID of the workspace where you want to add the tab or where it currently exists, as illustrated in the following code sample:
public bool GetAvailableParentsAsync(IHelper helper)
{
bool success = false;
using (ITabManager proxy = helper.GetServicesManager().CreateProxy<ITabManager>(ExecutionIdentity.System))
{
try
{
List<NameIDPair> response = proxy.GetAvailableParentsAsync(SampleWorkspace_ID).GetAwaiter().GetResult();
_logger.LogDebug("All availble parent tabs for workspace {WorkspaceID}", SampleWorkspace_ID);
foreach (NameIDPair nameID in response)
{
_logger.LogDebug("{Name} - {ArtifactID}", nameID.Name, nameID.ID);
}
success = true;
}
catch (Exception ex)
{
_logger.LogError("Get all available parents failed - {message}", ex.Message);
throw;
}
}
return success;
}
Before deleting a tab, you may want a list of other objects that are dependent on it, such as the children of a parent tab. For more information, see Deleting object dependencies on the Relativity 9.6 Documentation site.
The Tab Manager API includes the GetDependencyList() method for obtaining this information by passing the Artifact IDs of a workspace and an existing tab to it, as illustrated in the following code sample:
public bool GetDependencyList(IHelper helper)
{
bool success = false;
using (ITabManager proxy = helper.GetServicesManager().CreateProxy<ITabManager>(ExecutionIdentity.System))
{
try
{
List<Dependency> response = proxy.GetDependencyList(SampleWorkspace_ID, SampleTab_ID).GetAwaiter().GetResult();
_logger.LogDebug("List of all dependencies for an existing tab {TabID}", SampleWorkspace_ID);
foreach (Dependency dependency in response)
{
_logger.LogDebug("{ObjectType} - {Count} - {Connection}", dependency.ObjectType, dependency.Count, dependency.Connection);
}
success = true;
}
catch (Exception ex)
{
_logger.LogError("Get dependency list failed - {message}", ex.Message);
throw;
}
}
return success;
}
You can retrieve workspace-level metadata about admin and system tabs. This metadata includes fields that can't be updated and those that aren't supported for a specific tab. In general, the following guidelines apply to this metadata:
The following code sample illustrates how to call the GetMetaAsync() method by passing the SampleWorkspace_ID, which would be -1 to indicate the admin-level context. See Admin-level context.
public bool GetMetaAsync(IHelper helper)
{
bool success = false;
using (ITabManager proxy = helper.GetServicesManager().CreateProxy<ITabManager>(ExecutionIdentity.System))
{
try
{
Meta response = proxy.GetMetaAsync(SampleWorkspace_ID).GetAwaiter().GetResult();
_logger.LogDebug("Tab Meta for workspace {WorkspaceID}", SampleWorkspace_ID);
foreach (String unsupportedMeta in response.Unsupported)
{
_logger.LogDebug("Unsupported - {UnsupportedMeta}", unsupportedMeta);
}
foreach (String readOnlyMeta in response.ReadOnly)
{
_logger.LogDebug("ReadOnly - {ReadOnlyMeta}", readOnlyMeta);
}
success = true;
}
catch (Exception ex)
{
_logger.LogError("Get workspace level metadata failed - {message}", ex.Message);
throw;
}
}
return success;
}
The order assigned to a tab determines its position in the Relativity UI. Tabs with a lower order number are displayed on the left, while those with higher order numbers are displayed on the right. For more information, see Tabs on the Relativity 9.6 Documentation site.
The Tab Manager service includes the GetViewOrderList() method that you can use to retrieve the current order for tabs in a specific workspace. The following code sample illustrates how retrieve the tab order by calling the GetViewOrderList() method with the Artifact ID of a workspace. For the order of system or admin tabs, pass -1 instead of an Artifact ID. See Admin-level context.
public bool GetViewOrderList(IHelper helper)
{
bool success = false;
using (ITabManager proxy = helper.GetServicesManager().CreateProxy<ITabManager>(ExecutionIdentity.System))
{
try
{
List<TabViewOrder> response = proxy.GetViewOrderList(SampleWorkspace_ID).GetAwaiter().GetResult();
_logger.LogDebug("List of all tabs and their view order for workspace {WorkspaceID}", SampleWorkspace_ID);
foreach (TabViewOrder viewOrder in response)
{
_logger.LogDebug("{Name} - {ArtifactID} - {Order}", viewOrder.Name, viewOrder.ArtifactID, viewOrder.Order);
}
success = true;
}
catch (Exception ex)
{
_logger.LogError("Get view order list failed - {message}", ex.Message);
throw;
}
}
return success;
}
The tab manager API includes an endpoint that retrieves basic information about each tab the calling user can navigate to in a specific workspace. This endpoint returns a URL for navigating to each tab as well as tab metadata like the tab's name, order, visibility, parent, and other properties. To retrieve this data, call the GetAllNavigationTabs() method by passing the Artifact ID of the workspace. The following code illustrates how to retrieve navigation data for each tab in a workspace:
public bool GetAllNavigationTabs(IHelper helper)
{
bool success = false;
using (ITabManager proxy = helper.GetServicesManager().CreateProxy<ITabManager>(ExecutionIdentity.System))
{
try
{
List<NavigationTabResponse> response = proxy.GetAllNavigationTabs(SampleWorkspace_ID).GetAwaiter().GetResult();
foreach (NavigationTabResponse navigationTabResponse in response)
{
_logger.LogDebug("{Name} - {Order} - {URL}", navigationTabResponse.Name, navigationTabResponse.Order, navigationTabResponse.Url);
}
success = true;
}
catch (Exception ex)
{
_logger.LogError("GetAllNavigationTabs failed - {message}", ex.Message);
throw;
}
}
return success;
}
|
Community Updates |
|||
| Aero Developer FAQ | Evolving the Platform | Most recent release notes | |
| Learn more | Learn more | Learn more | |
|
Additional Resources |
|||
|
|
||
| Access Third-Party Tools with GitHub | Create .NET Apps Faster with NuGet | ||
| Visit github | visit nuget | ||
