Introduction

This course covers how to use the SystemWeaver 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
  • Familiarity with the system's meta model and data.


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.

Setting up a test server

See Setting up a test server for how to set up a local server to use for the exercises. The database used for this course is attached to this post. 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
  • We are now all set to begin working with the API


Bildresultat för exercise icon freeExercise 1. 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 SystemWeaver.API;

 //---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”


Bildresultat för exercise icon freeExercise 2. 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);


Find an item handle in the SystemWeaver client:

  • In the SystemWeaver client, copy an item and paste it in a textbox, notepad or anything similar and it will give you something like this: url:swap://localhost:1768/x0400000000000703
  • x0400000000000703 is the handle

Find a library handle in the SystemWeaver client:

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.


Bildresultat för exercise icon freeExercise 3. 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);


Bildresultat för exercise icon free Exercise 4. 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

SIDs

  • 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 out a item type's SID in the SystemWeaver client:

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


Bildresultat för exercise icon free Exercise 5. Item types

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


Bildresultat för exercise icon free Exercise 6. 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

The purpose of this part is to describe the process of working with Items & 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


Traversing an item structure #1

//Get Part-Items of an Item

IswItems items = parentItem.GetPartItems("partTypeSID");

 

foreach (IswItem item in items)

{

 //Do somthing with the item

}


Traversing an item structure #2

//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

}


Bildresultat för exercise icon free Exercise 7. 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;


Bildresultat för exercise icon free Exercise 8. 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


Bildresultat för exercise icon free Exercise 9. 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

The purpose of this part is to describe 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;

}


Bildresultat för exercise icon free Exercise 10. Attributes

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


Step 7. Descriptions (formatted text)

The purpose of this part is to describe 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
  • Conversions are not considered safe
  • Reading is always safe


Bildresultat för exercise icon free Exercise 11. Descriptions

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