This article covers how to use the SystemWeaver Client API in C#. The SystemWeaver API can be used in other development environments than Visual studio and in other programming and scripting languages. Popular usages include Python, Labview and more. 

Prerequisites

  • Knowledge of C# and .NET to complete the exercises presented in this course
  • Visual Studio installed
  • Familiar with the SystemWeaver meta model building blocks (e.g., Items, Parts and Attributes)
  • Familiar with the SystemWeaver Explorer Interface and common operations
  • Familiarity with your system's meta model and data
  • You have read Guidelines for API Usage
  • A test server (To set up your own, see Setting up a Test Server)
  • The SystemWeaver API files (contact your organization's SystemWeaver IT support to obtain the API files):
    • RVFUtility.dll or RVFUtility64.dll (depending on platform target)
    • SystemWeaverClientAPI.dll
    • SystemWeaverClientAPI.XML
  • In-house developed applications using .NET should use version 4.6.2 or later


See Software Releases with Client API and Database Versions for a list of SystemWeaver releases with their respective API version. 


The SystemWeaver ClientAPI is available via NuGet!
SystemWeaver.Connection is only compatible with .NET Framework.
SystemWeaver.Connection.Core is compatible with .NET Standard.


Warning

  • The .NET API is fully featured.
  • You can do anything the swExplorer can do and more.
  • No restrictions, take great care when doing writing operations. Large write operations should be done outside of normal business hours whenever possible so as not to affect performance for users.
  • Reading data is fine.
  • NEVER test an API application on a production server. Use a test server for this.


License Info

See attached document SystemWeaver API License Agreement for Non-Commerical Use (SYSTEMWEAVER API LICENSE AGREEMENT.txt). 

Setting up a Test Server

See Setting up a test server for how to set up a local server to use with the examples provided in this article. The database used for the examples is attached to this article. The username used to log in to the database is "student" and the password is "student".


Step 1. Setting up a Visual Studio Solution

Create a WPF Application.

  • The following dependencies can be found in the API+Client folder
  • Add Reference -> SystemWeaverClientAPI.dll
  • Make sure SystemWeaverClientAPI.XML is in the same folder as the dll to get intellisense
  • Add -> Existing item -> RVFUtility.dll or RVFUtility64.dll depending on platform target
  • Set ”Copy to output directory” to ”Copy always” or ”Copy if newer” for RVFUtility(64).dll
  • You are now set to begin working with the API

Try it! Set up your solution

  • Do not forget the copy option on RVFUtility(64).dll
  • Make sure the solution compiles

Step 2. Connecting to the SystemWeaver Server

// The Required Namespaces
using SystemWeaver.Common;
using SystemWeaverAPI;
 //---Try to connect to the server---
 try
 {
     SWConnection.Instance.LoginName  = "loginName";
     SWConnection.Instance.Password  = "password"; 
     SWConnection.Instance.ServerMachineName  = "servername"; 
     SWConnection.Instance.ServerPort  = 1234;
     SWConnection.Instance.Login();
 }
 catch  (SWInvalidUsernameOrPasswordException)
 {
     MessageBox.Show("Invalid username or password");
 }
 catch (Exception)
 {
     MessageBox.Show("Could not Connect to Server");
 }
  • SWConnection is a ”singleton”
  • Login() will fail if the username or password is invalid or if the server is inaccessible
  • If Login() fails, an exception will be thrown
  • ServerMachineName can also be an IP, for example ”127.0.0.1”

Try it! Connect to the server

  • LoginName: ”student”
  • Password: ”student”
  • ServerMachineName: ”127.0.0.1” / "localhost"
  • ServerPort: 1768 (or what you set it to)


Step 3. Accessing Data

What is a handle?

  • Unique identifier that exists for all SystemWeaver objects implementing the IswObject interface (items, parts, attributes, issues...)
  • Generated when a SystemWeaver object is created
  • Long number, for example: x0400000000000703

How do you find a handle?

  • Use the SystemWeaver client (see below)
  • Use the API (item.Handle, part.Handle, library.Handle, issue.Handle...)

What can you do with a handle?

//Getting items of a specific type in a library from a server  (items are stored in libraries)
IswLibrary library =  SWConnection.Instance.Broker.GetLibrary(handle);
IswItems items = library.GetItems("ItemTypeSID");

//Getting a specific item from a server
IswItem item = SWConnection.Instance.Broker.GetItem(handle);

Finding an item handle in the SystemWeaver client using the Properties view:


In the SystemWeaver client, copy an item, and then paste it into Notepad++ or similar. It will look something like this example SystemWeaver URL: url:swap://localhost:1768/x0400000000000703. In this example, x0400000000000703 is the handle.


Finding a library handle in the SystemWeaver client using the Manage libraries view:

With the item selected in the tree, load the view. The item's library properties will display.

Using a Handle in the Code

  • Find the handle
  • Paste it as a string in your program
  • Convert it to a handle:
long handle =  SWHandleUtility.ToHandle("x1300000000000702");

Tip: Refer to the SystemWeaverClientAPI.XML included in the API folder for a list of methods.


Try it! Get an item

  • Get an item
    • Use the client to find an item handle
    • SWHandleUtility.ToHandle(“x……..”);
    • Write code that uses the IswBroker to get the item
    • SWConnection.Instance.Broker.GetItem(handle);

Try it! Get a library

  • Get a library
    • Use the client to find a library handle
    • SWHandleUtility.ToHandle(“x……..”);
    • Write code that uses the IswBroker to get the library
    • SWConnection.Instance.Broker.GetLibrary(handle);


Step 4. Types and How to Traverse Structures

What is a SID?

  • Unique identifier that exists for all SystemWeaver types implementing the IswType interface (items, parts, attributes, issues...)
  • Architects decide what SID represents what SystemWeaver type.
  • Short string, for example: ”ASID”

How do you find a SID?

  • Ask your architect
  • Use the SystemWeaver client
  • Use the API (item.swItemType.SID, part.swPartType.SID...)

What can you do with a SID?

IswParts parts = item.GetParts("PSID"); //Part SID
IswItems items = item.GetPartItems("PSID"); //Part SID

if (part.IsSID("PSID")) //Part SID
{
 //Do something
}

if (item.IsSID("ISID")) //Item SID
{
 //Do something
}

IswAttribute attribute = item.Attribute("ASID"); //Attribute SID


Finding an item type's SID in the SystemWeaver client:

Use the Open Item and Select item type... options. Search for the item type in the Select Type dialog and note the item type SID displayed to the right.

Finding out a part type's SID in the SystemWeaver client using the Parts view:

  1. Select the owning item in the structure and load the Parts view. 
  2. Right-click on the grid header. 
  3. Select Expert>add field column, and add "SID".

Try it! Item types

  • Get the item “x040000000000018B”
  • Check if the item is of type “3PTA”
  • Use IsSID

Try it! Part types

  • Get the item “x040000000000018B”
  • Get the Parts of the item, use the SID “XESX”
  • Check if the parts is of type “XESX”
  • Loop over the IswParts returned, use IsSID


Step 5. Working with Items and Parts

This section describes the process of working with Items and Parts using the .NET API.

Items

What is an Item?

  • IswItem implements the IswObj interface, which means that it...
    • Has a type (SID)
    • Can have attributes
  • IswItem can also have parts
  • IswItem supports versioning

How do you find an item?

  • Use a handle
  • Traverse an item structure and find child items
// Item: Important Properties-----------------------------
long handle =  item.Handle;                           // The Unique Identifier
string itemTypeIdentifier =  item.swItemType.SID;     // The item's Type Identifier
long ancestorHandle =  item.AncestorHandle;           // The Version Chain identifier
// Item: Important Methods--------------------------------
bool isSID = item.IsSID("ASID");                      // Checks whether or not an Item is a specific Type
IswAttribute  attribute = item.Attribute("ASID");     // Gets the attribute of the given SID
IswParts  parts = item.GetParts("partSID");           // Gets the parts of the given type from the Item
IswItems  partItems = item.GetPartItems("partSID");   // Gets the parts Items of the given type from the Item

Parts

What is a part?

  • IswPart implements the IswObj interface, which means that it...
    • Has a type (SID)
    • Can have attributes
  • A relation between items or other parts
  • Has a DefObj (the IswObj that the Part points to, usually an item)

How do you find a part?

  • Item.GetParts();
  • Item.GetAllParts();

What can you do with a part?

// Part: Important Properties-----------------------------
long parthandle = part.Handle;                      // The Unique Identifier
string partTypeIdentifier = part.swPartType.SID;    // The Part  Type Identifier
IswItem  defObj = part.DefObj as IswItem;// The Item that the Part is pointing to
IswItem  owner = part.Owner;// The  owner of the Part
// Part: Important Methods--------------------------------
bool partIsSID = part.IsSID("ASID");                 // Checks whether or not an Item is a specific Type
IswAttribute  partAttribute = part.Attribute("ASID");// Gets the attribute of the given SID

Items and Parts

Example 1: Traversing an item structure

//Get Part-Items of an Item
IswItems items = parentItem.GetPartItems("partTypeSID");

foreach (IswItem item in items)
{
 //Do somthing with the item
}

Example 2: Traversing an item structure

//Get all of the Part-Items of an Item
IswParts parts = parentItem.GetAllParts();

foreach (IswPart part in parts)
{
 IswItem item =  part.DefObj as IswItem;
 if (item == null)
continue;

 //Do somthing with the item
}

Try it! Visualize and item structure

  • Create a TreeView control
  • Get item with handle: “x040000000000018B”
  • Traverse the item and its part-items and create TreeViewItems for all items
  • Add the first item as a TreeViewItem in the TreeView control


  • Hint: Recursion


Item Versioning

  • IswItem supports versioning
  • Use the NewVersion(); method to create a new version of the item
  • If a newer version already exists a branch will be created implicitly
  • Example:

IswItem newItem = item.NewVersion();

string version =  item.VersionNumber;

Try it! Versioning

  • Make a new version of the item with handle “x040000000000018B”
  • Output the old and the new version number in a MessageBox
  • Try running this multiple times. What happened?

Item statuses

  • IswItem has a Status property
  • SWItemStatus is an enum:
    • Work: can be edited if the user has access to the item’s library
    • Frozen: has to be thawed before being edited by setting the status to work
    • Released: this item is locked for all editing. New version is required for editing
    • CSReleased: set by the server to indicate that the complete structure is released
    • CheckedOut: do not use, deprecated and will be removed

Try it! Statuses and versioning

  • Get the item with handle “x040000000000018B”
  • Set the status to Frozen

item.Status = SWItemStatus.Frozen;

  • Set the status to Work

item.Status = SWItemStatus.Work;

  • Set the status to Released

item.Status = SWItemStatus.Released;

  • Set the status back to Work. What happened?


Step 6. Attributes

This section describes the process of working with Attributes using the .NET API.

What is an attribute?

  • Can be attached to any type implementing IswObj to store extra information
  • Different data types
  • Different dimensions
  • SID to identify it

How do you find an attribute?

  • Look up the SID using the Client or ask your architect
  • Use the API

What can you do with an attribute?

//Attribute: Important Properties-------------------------
string  attributeTypeIdentifier = attribute.AttributeType.SID; // The Attribute Type  Identifier
string valueString =  attribute.ValueAsString; // The Attribute value in string format
string valueXml =  attribute.ValueAsXML;//  The Attribute value in XML format
//Attribute: Important Methods----------------------------
bool attributeIsSID =  attribute.IsSID("ASID"); // Checks whether or not an Item is a specific Type

The DataType and DataDimension decides how a value is stored in an attribute:

//Getting a specific attribute
IswAttribute attribute = item.Attribute("AttributeSID");
if  (attribute.AttributeType.DataType == SWAttributeDataType.Integer &&
 attribute.AttributeType.DataDimension  == SWAttributeDataDimension.Single)
{
 //Get the value of the attribute as a string
 string attributeValue =  attribute.ValueAsString;
}
else if  (attribute.AttributeType.DataType == SWAttributeDataType.Integer &&
 attribute.AttributeType.DataDimension  == SWAttributeDataDimension.Array)
 {
 //Get the value of the attribute as XML
 string attributeValueAsXML =  attribute.ValueAsXML;
}

Try it! Attributes

  • Get the attribute “PRIO” from the item with handle “x0400000000000048”
  • Output the attribute value in a MessageBox


Step 7. Descriptions (formatted text)

This section describes the process of working with Descriptions using the .NET API.

What is a description?

  • RichView Format (RVF)
  • May contain formatted text and images
  • Is available on many but not all SystemWeaver objects (IswItem, IswIssue...)
  • Stored as zlib compressed RVF

How do you find a description?

  • Use the SystemWeaver client
  • Use the API (item.Description, issue.Description...)

What can you do with a description?

//Get the item description as plaintext. This will skip images  and formatting.
string description =  SWDescription.DescriptionToPlainText(item.Description, item.Broker);

//Set the item description.
//Doing this with a description that previously contained images  and formatting will cause data loss. 
item.Description =  SWDescription.PlainTextToDescription(description);

//Formatted RTF string from RVF, formatting not supported by RTF  will potentially be lost. 
string descriptionRTF =  SWDescription.DescriptionToRtf(item.Description, item.Broker);

//Convert RTF back to RVF, formatting not supported by RVF will  potentially be lost. 
item.Description =  SWDescription.RtfToDescription(descriptionRTF);

Advice

  • Writing to descriptions is safe if they are empty or you are replacing existing content
  • Conversions are not considered safe
  • Reading is always safe

Try it! Descriptions

  • Get item with handle “x0400000000000048”
  • Output Name + Description in a MessageBox