DataScope Select - REST API

Close Menu
Expand All Collapse All
Introductory Tutorials Tutorials Introduction Programming without SDK Tutorial REST API Tutorials REST API Tutorials Introduction REST API Tutorial 1: Connecting to the DSS server REST API Tutorial 2: On Demand End of Day Extraction REST API Tutorial 3: On Demand intraday extraction, embargo REST API Tutorial 4: On Demand price history extraction REST API Tutorial 5: On Demand corporate actions extraction REST API Tutorial 6: On Demand ownership data extraction REST API Tutorial 7: On Demand T&C extraction REST API Tutorial 8: On Demand composite extraction REST API Tutorial 9: On Demand extraction: instrument list REST API Tutorial 10: GUI control calls: immediate extract REST API Tutorial 11: Search by Instrument REST API Tutorial 12: Search for an Equity REST API Tutorial 13: Search for a Future or Option REST API Tutorial 14: On Demand price history extraction raw .Net SDK Tutorials .Net SDK Tutorial 1: Connecting to the DSS server .Net SDK Tutorial 2: GUI control calls: List, report, sched .Net SDK Tutorial 3: GUI control calls: Validate, extraction .Net SDK Tutorial 4: GUI control calls: Embargo, note files .Net SDK Tutorial 5: On Demand: EoD extraction .Net SDK Tutorial 6: On Demand: EoD extraction, file I/O .Net SDK Tutorial 7: On Demand: large instrument lists .Net SDK Tutorial 8: On Demand: Terms & Conditions .Net SDK Tutorial 9: On Demand: Composite extraction .Net SDK Tutorial 10: Search by Instrument .Net SDK Tutorial 11: Search for Equity .Net SDK Tutorial 12: Search for Future or Option

.Net SDK Tutorial 8: On Demand: Terms & Conditions

Last update May 2020
Environment Windows
Language C#
Compilers Microsoft Visual Studio 2012/2013
Prerequisites DSS login, internet access, having done the previous tutorials
Source code Download .Net SDK Tutorials Code

Tutorial purpose

This is the eighth tutorial in a series of .Net SDK tutorials. It is assumed that the reader has acquired the knowledge delivered in the previous tutorials before following this one.

This tutorial is similar to Tutorial 5, but replaces the End of Day extraction with a T&C (Terms and Conditions) extraction.

The use case is to cross reference instrument codes, i.e. retrieve several instrument codes (RIC; Cusip, ISIN, Sedol, etc.), for a list of instruments (with different instrument codes). For each input instrument code, only 1 RIC is returned (the primary RIC).

We continue using the simplified high level API calls for On Demand extractions. We:

  • Create an instrument list array, and an array of data field names, outside of the DSS server.
  • Create and run an on demand data extraction on the DSS server, wait for it to complete.
  • Retrieve and display the data and the extraction notes (including maintenance notes).
  • We also analyze the extraction notes .


Table of contents


Getting ready

Opening the solution

The code installation was done in Tutorial 1.

Opening the solution is similar to what was done in the previous tutorials:

  • Navigate to the \DSS REST API\Tutorial 8\Learning folder.
  • Double click on the solution file rest_api_TandC.sln to open it in Microsoft Visual Studio.


Referencing the DSS SDK

Before anything else, you must reference the DSS REST API .Net SDK in the Microsoft Visual Studio project.

Important: this must be done for every single tutorial, for both the learning and refactored versions.

This was explained in the tutorial 2; please refer to it for instructions.


Viewing the C# code

In Microsoft Visual Studio, in the Solution Explorer, double click on Program.cs and on DssClient.cs to display both file contents. Each file will be displayed in a separate tab.


Setting the user account

Before running the code, you must replace  YourUserId  with your DSS user name, and  YourPassword  with your DSS password, in these 2 lines of Program.cs:

        private static string dssUserName = "YourUserId";
        private static string dssUserPassword = "YourPassword";

Important reminder: this must be done for every single tutorial, for both the learning and refactored versions.

Failure to do so will result in an error at run time (see Tutorial 1 for more details).


Understanding the code

We shall only describe what is new versus the previous tutorials.


This is the same as the refactored version of Tutorial 7, except for the leading comment, and one added method, to create and run a T&C (Terms and Conditions) extraction.

This is very similar to the Tutorial 5 method to create and run an EoD extraction, except that this time we declare a new TermsAndConditionsExtractionRequest. Again, we use as parameters the instrument identifiers and requested field names arrays, defined in Program.cs:

public ExtractionResult CreateAndRunTandCExtraction(
    InstrumentIdentifier[] instrumentIdentifiers, string[] contentFieldNames)
    TermsAndConditionsExtractionRequest extractionTandC = new TermsAndConditionsExtractionRequest
        IdentifierList = InstrumentIdentifierList.Create(instrumentIdentifiers),
        ContentFieldNames = contentFieldNames,
        //Optional conditions:
        //Condition = new TermsAndConditionsCondition
        //    IssuerAssetClassType = IssuerAssetClassType.AllSupportedAssets,
        //    ExcludeWarrants = false,
        //    //DaysAgo = 3, //Use either DaysAgo or StartDate
        //    StartDate = new DateTimeOffset(new DateTime(1996, 1, 1)),
        //    FixedIncomeRatingSources = FixedIncomeRatingSource.StandardAndPoors
    //Run the extraction.
    //This call is blocking, it returns when the extraction is completed:
    return extractionsContext.ExtractWithNotes(extractionTandC);

This is just one of many possibilities. The Example Application explained in the Quick Start illustrates many more On Demand extractions.



Creating the instrument array

We create an array of 4 instrument identifiers and populate it manually, using the helper method we created in Tutorial 2:

InstrumentIdentifier[] instrumentIdentifiers = PopulateInstrumentIdentifiers();

The method is very simple, as the purpose of this Tutorial is to concentrate on the extraction itself. For a more productized example with details on handling large instrument lists read from file, see tutorial 7.

For the demo we use 4 instruments, each one defined using a different identifier type: 1 Cusip, 1 Ric, 1 Isin and 1 Sedol.

We will use this array when we define the extraction.


Creating the field name array

To create the field name array we proceed just like in the previous tutorials, calling the helper method we created in Tutorial 2:

string[] requestedFieldNames = CreateRequestedFieldNames();

For this demo the helper method defines a list of fields including 5 instrument codes (the use case is cross referencing), and the currency code:

static string[] CreateRequestedFieldNames()
    string[] requestedFieldNames = { "RIC", "CUSIP", "ISIN", "SEDOL", "Issuer OrgID",
                                     "Currency Code" };
    return requestedFieldNames;

As a reminder, an explanation on how to choose field names is available in Tutorial 2, at the end of the section on report templates, under the heading: How to choose a report template format, and find out what field names are available ?

We will use this array when we define the extraction.


No report template or schedule creation

On Demand extractions do not require these, as explained in Tutorial 5.


Creating and running the On Demand extraction

To create and run the On Demand T&C extraction, we call our new DSS client helper method:

ExtractionResult extractionResult =
    dssClient.CreateAndRunTandCExtraction(instrumentIdentifiers, requestedFieldNames);
DssCollection<ExtractionRow> extractionDataRows = extractionResult.Contents;

It is a blocking API call which only returns when the extraction is complete, so there is no need for code to check for extraction completion.


Retrieving the extracted data and extraction notes

The On Demand extraction returns extraction data rows. We process them using the helper method from tutorial 5:


We also process the extraction notes:



No cleaning up

As stated previously, cleanup on the DSS server is not required, as there is nothing to delete in this case.


Full code

The full code can be displayed by opening the appropriate solution file in Microsoft Visual Studio.



List of the main steps in the code:

  1. Authenticate by creating an extraction context.
  2. Create an array of financial instrument identifiers.
  3. Create an array of field names.
  4. Create an extraction.
  5. Run the extraction, wait for it to complete.
  6. Retrieve the extracted data and extraction notes.

We do not create a report template or schedule, and there is no need to cleanup.


Refactored version

There is none for this tutorial.


Code run results

Build and run

Don’t forget to reference the DSS SDK, and to set your user account in Program.cs !


Successful run

After running the program, and pressing the Enter key when prompted, the final result should look like this:

Returned session token: <token>
Press Enter to continue

We created an array with 5 instrument identifiers, and an array of field names, outside of DSS.

Next we will launch a direct on demand T&C extraction,
using these 2 arrays.
Press Enter to continue

Please be patient and wait for the extraction to complete ...

Returned list of field names:
RIC,CUSIP,ISIN,SEDOL,Issuer OrgID,Currency Code,
Press Enter to continue

Returned field values:
00209TAB1=RRPS, 00209TAB1, US00209TAB17, 2166502, 172642, USD
IBM.N, 459200101, US4592001014, 2005973, 18228, USD
IBM.N, 459200101, US4592001014, 2005973, 18228, USD
LP71000002, , GB00B1YW4409, B1YW440, 100691344, GBp
, 438516AC0, US438516AC05, BP84RP2, 18181, USD

Extraction completed.
Number of data rows: 5
Number of valid (non empty) data rows: 5
Press Enter to continue

Extraction Notes:
Extraction Services Version 14.0.41655 (18a2bf29b489), Built Apr 13 2020 21:47:48
Processing started at 05/25/2020 06:42:55.
User ID: 9008895
Extraction ID: 444334646
Schedule: _OnD_0x071be3fbb14198bd (ID = 0x071be3fbed3198bd)
Input List (5 items): _OnD_0x071be3fbb14198bd (ID = 071be3fbdf8198bd) Created: 05/25/2020 06:42:52 Last Modified: 05/25/2020 06:42:53
Schedule Time: 05/25/2020 06:42:53
Report Template (12 fields): _OnD_0x071be3fbb14198bd (ID = 0x071be3fbb33198bd) Created: 05/25/2020 06:42:52 Last Modified: 05/25/2020 06:42:52
(CSP,438516AC0,CPN) is inactive.
Processing completed successfully at 05/25/2020 06:42:55, taking 0.72 Secs.
Extraction finished at 05/25/2020 06:42:55 UTC, with servers: x04A05, QSHC12 (0.1 secs), QSSHA1 (0.1 secs)
Usage Summary for User 9008895, Client 65508, Template Type Terms and Conditions
Base Usage
        Instrument                          Instrument                   Terms          Price
  Count Type                                Subtype                      Source         Source
------- ----------------------------------- ---------------------------- -------------- ----------------------------------------
      1 Corporate                           Investment Grade             N/A            N/A
      1 Corporate                                                        N/A            N/A
      2 Equities                                                         N/A            N/A
      1 Mutual Funds                                                     Lipper         N/A
      5 Total instruments charged.
      0 Instruments with no reported data.
      5 Instruments in the input list.
Writing RIC maintenance report.


SUCCESS: processing completed successfully.

Inactive instruments messages:
(CSP,438516AC0,CPN) is inactive.

Press Enter to continue


Potential errors and solutions

If the user name and password were not set properly, an error will be returned. See Tutorial 1 for details.



This tutorial continued with the simplified high level calls for On Demand extraction requests, with a simple use case for instrument cross referencing.

Now move on to the next tutorial, which uses a composite extraction for a similar use case.

Tutorial Group: 
.Net SDK Tutorials