[-]
  
 [+]
  
[-]
  
  
 [+]
[-]
  
  
 [+]
 [+]
  
 [+]
  
  
[-]
  
  
 [+]
 [+]
 [+]
  
 [+]
[-]
  
  
 [+]
 [+]
[-]
  
  
 [+]
 [+]
[-]
  
  
 [+]
 [+]
[-]
  
  
 [+]
 [+]
[-]
  
  
 [+]
 [+]
[-]
  
  
 [+]
 [+]
[-]
  
  
  
  
[-]
  
  
[-]
  
  
  
  
Updated on 11/7/2019
Relyence User Guide
Getting Started with the Relyence API
Direct link to topic in this publication:

Getting Started with the Relyence API

If you would like to review a video overview of this Getting Started Guide, go to our online video for the Relyence API.

 Before using the Relyence API, you must:

1. Have Microsoft Visual Studio installed on your system.

a. If you already have Visual Studio installed, you must have the .NET desktop development Workload installed. If not installed, follow the instructions here to install this Workload.

b. If you do not have Microsoft Visual Studio installed, go here to download it. Once downloaded, install it on your system. Be sure to select the .NET desktop development Workload during installation. 

2. Be able to create Windows Forms applications.

3. Download the Relyence API SDK. Unzip the Relyence API SDK once downloaded.

The Relyence API SDK package includes 3 items:

a. RelyenceApiSDK: the SDK with all the Relyence API wrapper functions you will need to use the Relyence API.

b. RelyenceBrowser: a complete testing application that includes sample code for all the functions available in the Relyence API.

c. Tutorial: a complete version of the code sample that is built in this Getting Started with the Relyence API tutorial.

You are now ready to begin using the Relyence API. For this guide, we will walk through adding a Problem to Relyence FRACAS.

1. Sign in to Relyence

To begin, make sure you are signed in to Relyence. For details on signing in, see Signing in and Signing out.

2. Open the Example Analysis

First, let's make sure Relyence FRACAS is active.

After you have signed in, you may see a Welcome dialog. If a Welcome dialog does not appear, click Welcome to Relyence from the Help dropdown menu in the upper right of the Relyence header bar.

Click the FRACAS tab on the left to activate Relyence FRACAS. Then click Open Example Analysis(Note: If you were previously working on an Analysis, you will see the Continue where I left off option at the top of this dialog, otherwise it will not appear.)

For this tutorial, we will use the Drone Example supplied with Relyence FRACAS.

When you open an Example, you will see the Revert Example pop up appear. You are free to make changes and save your changes to the Example Analyses. If you want to revert to the original Example at any time, click Revert Example. You will get a message asking if you are sure before your changes are discarded. Click Got it! to dismiss the pop up.

For this tutorial, we assume an unmodified original Example is being used. If you are not sure if you are using an unmodified version of the Example, click Revert Example from the Sidebar. You will be asked if you want to lose your changes and reopen the Example in its original version. Click Yes.

If you continue with a modified version, just be aware that screen shots or other functions may not operate exactly as described in this tutorial.

The Drone Example with its data will appear in the main window.

3. Create a Visual Studio project

Open Visual Studio and select File>New>Project to create a new Visual Studio project.

In the right pane, search for Windows Form Application and select the Visual C# Windows Form App in the center pane. In the Name field, enter "RelyenceApiTutorial" for the project name. Click OK to complete creation of a new Windows Form project.

4. Get set up to run our Relyence API example

Before coding, we want to set up our new project as the startup project.

1. Set our project as the StartUp Project: In Visual Studio Solution Explorer, right click on our RelyenceAPITutorial project and select Set as StartUp Project.

2. Add a button to make it easy for us to execute our Relyence API function:  Select View>Toolbox from the main menu.

In the Toolbar dialog, expand the Common Controls heading, drag and drop the Button control onto our form.

Right click on the Button and select Properties from the menu.

In the Text property, enter a label for our new button "Run Test!".

3. Add the Relyence SDK project to our Microsoft Visual Studio Solution:

a. Click File>Add>Existing Project from the main menu.


In the Add Existing Project dialog, navigate to the Relyence API SDK project and click Open. If a Security Warning appears, click OK.


b. The Relyence API SDK contains references to NuGet packages that you may or may not have installed on your system. To ensure you have all the necessary packages, click Tools>NuGet Package Manager>Package Manager Console to activate the NuGet Package Manager console.


Click the Restore button. 


5. Write the API Code

For simplicity in this example, we will add all our Relyence API code in to the button click handler for the Run Test! button we added. Double click the Run Test! button to view the code for the Form we added, Form1.

1. Add the credentials needed to connect to the Relyence API. Add variables to hold our credentials.

Add the following code:

// credentials

string apiKey = "";

string username = "";

string password = "";

string version = null;

string website = null;

2. Generate your Relyence API Key if necessary. 

 If you already have a Relyence API Key, skip this step.

To generate your Relyence API Key, go to Relyence and click About Relyence from the Help menu. The About Relyence dialog will appear. Click the API Key button. (Note: If the API Key button does not appear, you do not have permission to generate an API Key. Your Relyence Administrator controls this setting.)


The Manage API Key dialog appears.

The first time you use this feature, the API Key field will show <No API Key Assigned>. Once an API Key has been generated, the API Key will be displayed. 

If an API Key appears, copy it from the API Key field. If the API Key field is blank, click the Generate API Key to generate your unique Relyence API Key. Copy the newly generated API Key.

3. Enter your credentials

Go back to Visual Studio and update the variables:

// credentials

string apiKey = <paste in your copied API Key>;

string username = <your Relyence username (email)>;

string password = <your Relyence password>;

string version = null;

string website = null;



For this tutorial, we will leave Version and Website blank. If you were using a different version of the Relyence API you would add that in the Version variable. If you were using an on-premise version of Relyence, you would add in your website address used to access Relyence.

4. Create an instance of the Relyence API and initialize a connection.

Add the following code:

var relyenceApi = new RelyenceAPI(apiKey, username, password, version, website);

if (relyenceApi.intializeConnection())

{

  

}

5. Add a Reference to our project to the Relyence API.

RelyenceAPI will display underlined in red, indicating the we need to add this to our Tutorial project.

Right click on the References section of the Tutorial project and click Add Reference....

In the References Manager, select the RelyenceApiSDK checkbox, and then click OK.



Add a "Using" clause to our code so that our project can properly find the RelyenceAPI. At the top of our button code, add the line "using RelyenceApiSDK;" and the end of all the "using" clauses.

6. Get the ID of our Analysis and its data

We know the name of the FRACAS Analysis we are using (Drone Example) for this example, but we need to obtain the ID of this Analysis.

Add this code:

// get the Id of the Analysis that we want to insert a Problem into

var resultJson = await relyenceApi.GetAnalyses();


Our "await" line is underlined in red because we are attempting to call an asynchronous method from within a synchronous function. To correct, we'll make our Button handler function asynchronous. Add "async" to our button1_click function:

private async void button1_Click(object.sender, EventArgs e)

The GetAnalyses will retrieve a list of all our Analyses. We will want to convert these results into a more readable format by deserializing the data, and find the Analysis we want to use. Add the following code:

List<Analysis> analyses = JsonConvert.DeserializeObject<List<Analysis>>(resultJson);

if (analyses == null || analyses.Count == 0)

{

MessageBox.Show("Unable to get Analyses.", "Analysis Error", MessageBoxButtons.OK, MessageBoxIcon.Exclamation);

return;

}


//find the Analysis we need

Analysis analysis = analyses.Where(a => a.Name == "Drone Example").FirstOrDefault();

if (analysis == null)

{

MessageBox.Show("Unable to find Analysis.", "Analysis Error", MessageBoxButtons.OK, MessageBoxIcon.Exclamation);

return;

}


Analysis and JsonConvert are underlined in red, indicating we are referencing items Visual Studio does not recognize. We'll add classes for these unknown entities. Add the following code outside of the Form1 class, but still inside the RelyenceApiTutorial namespace:

public class Analysis

{

[JsonProperty("id")]

public int Id;

 

[JsonProperty("name")]

public string name;

}

 

public class Subsystem

{

[JsonProperty("Id")]

public int Id;

 

[JsonProperty("Name")]

public string Name;

 

[JsonProperty("ParentId")]

public string ParentId;

 

[JsonProperty("Level")]

public int Level;

}

 

public class Problem

{

[JsonProperty("Id")]

public int Id;

 

[JsonProperty("Problem ID")]

public string ProblemID;

 

[JsonProperty("Description")]

public string Description;

 

[JsonProperty("Date Created")]

public DateTime? DateCreated;

 

[JsonProperty("Team Members")]

public string TeamMembers;

 

// not a real database field.  Holds the temporary results from an Insert or Update action.

[JsonProperty("Results Log")]

public string ResultsLog;

}


Feel free to reuse these classes in any Projects you make. You can easily add more members to the classes if you need to retrieve more data that we are using in the example.

To add in the reference for JsonConvert, we need to add in a "using" clause and download the NuGet package.

Select Tools>NuGet Package Manager>Package Manager Console to activate the Package Manager Console.


Type the following command: "Install-Package Newtonsoft.Json" and then press the <Enter> key.


Close the tab.

Add the following code to the top of the file in the "using" clauses section:

using Newtonsoft.Json;


7. Add a new Problem to a subsystem in our Analysis

Add the following code:

// get the list of subsystems in this Analysis.  We'll associate our Problem with the first one.  There is always at least one in an Analysis file

resultJson = await relyenceApi.GetSubsystems(analysisId, false, false);

 

List<Subsystem> subsystems = JsonConvert.DeserializeObject<List<Subsystem>>(resultJson);

if (subsystems == null)

{

MessageBox.Show("Unable to retrieve Subsystems", "Subsystems Error", MessageBoxButtons.OK, MessageBoxIcon.Exclamation);

return;

}

var subsystemId = subsystems[0].Id;



The GetSubsystems() function will return a list of the subsystems in the Analysis. For this tutorial, we will just use the first subsystem in this list. 

Add in the FRACAS Problem data we want to insert. Add the following code:

// data for our new Problem

Dictionary<string, object> listValues = new Dictionary<string, object>();

listValues["Description"] = "This is my new Problem added through the API.";

listValues["Date Created"] = DateTime.UtcNow;

listValues["Team Members"] = "John Smith";

Perform the insert. Add the following code:

// insert new Problem.  Not associating with an Incident, so pass a zero.

resultJson = await relyenceApi.InsertProblem (analysis.Id, subsystemId[0].Id, 0, listValues);

Problem problem = JsonConvert.DeserializeObject<Problem>(resultJson);

if (problem == null)

{

MessageBox.Show("Error inserting Problem", "Problem Insert Error", MessageBoxButtons.OK, MessageBoxIcon.Exclamation);

return;

}


In this example, we have set the function parameters to data we previously retrieved. The returned problem variable include the ID, the Problem ID, and the Results Logs. If you want to access or add more data in the future to this Problem, you can use the returned ID.

8. Retrieve the Problem

We'll add some code to retrieve our newly added Problem, just to prove it was actually added to our Analysis. We'll add a list of fields to retrieve and we'll use the ID we obtained from our insert.

Add the following code:

// query for newly added Problem.  Pass zeroes for subsystem and incident ids since we're only looking for one record

 

// list of Problem fields to retrieve for the record

List<string> fields = new List<string>();

fields.Add("Problem ID");

fields.Add("Description");

fields.Add("Date Created");

fields.Add("Team Members");

fields.Add("Closed");

 

resultJson = await relyenceApi.GetProblems(analysis.Id, fields, problem.Id);

List<Problem> problems = JsonConvert.DeserializeObject<List<Problem>>(resultJson);

if (problems == null || problems.Count == 0)

{

MessageBox.Show("Error retrieving Problem", "Problem Read Error", MessageBoxButtons.OK, MessageBoxIcon.Exclamation);

return;

}



6. Execute our Relyence API function

Coding is complete, so we're ready to test. With Debug selected in Visual Studio, click Start. Click the Run Test! button on our Windows Form. 


Go back to Relyence.

Click Close to close the Manage API Key dialog. Click Close to close the My Relyence Modules dialog.

In the Sidebar, click Problems to display the FRACAS Problems Table. Your new Problem (Problem005) will appear in the Table. Note: depending upon your system, you may have to click the Refresh button in the toolbar to see the newly added Problem.

7. Moving On

This example is intended to get you up and running with the Relyence API. The C# code used in this tutorial can be downloaded here to use as a starting point.

If you need help in setting up your own API functions, feel free to contact our technical support team.