Getting Started: Getting Up and Running Using Visual Studio and C#

Pre-Requisites

This guide assumes you have a working knowledge of Visual Studio and the C# language as well as a basic understand of web services. Before we begin you will need to make sure you have the following items available to you:

• Visual Studio (2015 or higher)
• IDI provided SSL certificates for signing communications
• IDI provided WSDL for the SOAP Web Services
• Web Service User Credentials (Provided by IDI)
• IDI Configured Environment for test and production
• IDI has configured their firewall to allow requests from your IP address.

Visual Studio

This guide assumes you are have installed Visual Studio 2015. You can use different versions but the names and locations of features can change from version to version.

SSL Certificates

In order to communicate with IDI Web Services you need to be able to sign your communications with a certificate provided by IDI. These certificates must be installed on any work station or server that will communicate with IDI Web Services.

Web Service Credentials

IDI will provide you with a login id and password for authenticating to IDI’s security server. These credentials should have been provided as part of your kick start package, if you did not receive them, you should contact your Account Manager.

Configured Environment

Before you can connect to IDI’s Web Services you must have an environment configured. Configuration includes setting up CostGuard Services, databases, and seed data. Once configured you will be provided an alpha numeric Customer ID usually consisting of 3 digits and 2 numbers (i.e.. IDI01). This ID is used as part of the destination URL for IDI Web Services.

Configuring Your IP Address to communicate with IDI

In order to connect to IDI’s Web Services farm you need to provide the IP Address (or range of IPs) that will connect to the Web Services. IDI will then add those addresses to their whitelist of allowed connections. Speak with your Account Manager for more information on how to request this service.

Windows Identity Foundation

If you have not already, you must install the Windows Identity Foundation SDK at
http://www.microsoft.com/en-us/download/details.aspx?id=4451

Installing your certificates

Detailed instructions for installing certifications can be found in the following article:

Getting Started: Installing Certificates on Windows

Preparing your Visual Studio project

The generally excepted way to consume IDIs Web Services from Visual Studio is to add a Service Reference to your project and let it boot strap the necessary objects for you.

Required Frameworks

IDI’s web services make use of the Windows Identity Foundation SDK and WCF Data Services so your project will need references to the following namespaces:

System.IdentityModel
Microsoft.IdentityModel
System.Data.Service.Client

Adding the Service Reference

First you must find the URL to the web service WSDL. To do this, open the Web API Documentation and then select the web service(s) you wish to use in your project (in this case we’ll choose the Customer Service) and find the document main section. In the window on the right you will see a link to the web service WSDL file. Right click that link and select copy link address.

Next open your Visual Studio project and find the Service References section in the Solution Explorer. Right click and select Add Service Reference.

When the dialog appears, paste in the link address to the WSDL in the Address box and select the Go button. Give the web service a name space (in our examples we will refer to it as CustomerServiceReference1).

Edit the App.Config

Open the App.Config (or Web.Config) and find the <binding> element created for the CustomerService and remove it.

Insert the new binding below and replace the <Security Service Address> with the address of your Security web service.

<binding name=”FederationBinding”>

<textMessageEncoding messageVersion=”Soap12″ />

<security authenticationMode=”IssuedTokenOverTransport” messageSecurityVersion=”WSSecurity11WSTrust13WSSecureConversation13WSSecurityPolicy12BasicSecurityProfile10″>

<issuedTokenParameters keyType=”SymmetricKey” tokenType=”http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1″>

<issuer address=”<Security Service Address>”

binding=”ws2007HttpBinding” bindingConfiguration=”UserNameBinding” />

</issuedTokenParameters>

</security>

<httpsTransport />

</binding>

</customBinding>

<ws2007HttpBinding>

<binding name=”UserNameBinding”>

<security mode=”TransportWithMessageCredential”>

<message clientCredentialType=”UserName” establishSecurityContext=”false” />

</security>

</binding>

</ws2007HttpBinding>

Find the <endpoint > entry for the new CustomerService under the client tag and replace the address with the address of your Customer Web Service and the bindingConfiguration with FederationBinding.

Additionally, add a the <endpoint> entry for the new binding you added above:

<endpoint address=”<Security Service Address>”

binding=”ws2007HttpBinding”

bindingConfiguration=”UserNameBinding”

contract=”Microsoft.IdentityModel.Protocols.WSTrust.IWSTrustChannelContract”

name=”SecurityTokenServiceIssuePort” />

Replace the <Security Service Address> with the address of your Security web service.

Adding additional web service references

When adding additional services remove the binding entry under customBinding and update the new <endpoint> entries with the proper web service address and bindingConfiguration with FederationBinding.

Connecting to the Customer Web Service

This section heavily references the sample project included in this article, it is recommended you open this project for reference as you read further.

Obtaining A Security Token

All web service requests require a Token from the security web service. This article does not cover obtaining a security token, but the sample project includes a Utilities.cs class with a function to obtain the token called CreateSecurityToken();

Create A Channel Factory

The Utility.cs class uses the function CreateCustomerChannel(SecurityToken securityToken) to create a channel factory. This function will return a CustomerServicePortTypeChannel object that you will use to call the web service functions.

Making a Create Customer Request

The class Customer.cs includes an example of how to create a new Customer in the web service. Making this (and other requests to this service) requires a few steps:

1. Create a Requestor Object. This object is used to pass global data when necessary. For our case it will be an empty object.
2. Obtain a Security Token

   //Obtain a security token
   SecurityToken securityToken = Utilities.CreateSecurityToken();

3. Obtain a Channel Object using the Security Token and populate the AutorizationToken property with “AuthorizationToken”.

   //Create a Channel object for the Customer web service
   CustomerServicePortTypeChannel chanel = Utilities.CreateCustomerChannel(secutiryToken);
   requestor.AuthorizationToken = "AuthorizationToken";
   

4. Create a CreateCustomerReq object. This object contains the details of your Create Customer call. Each operation in the web service has an associated Req object to specify the parameters of the request object (i.e. ModifyServiceReq, ModifyCustomerReq, etc.).

   //Populate the request details
   CreateCustomerReq req = new CreateCustomerReq
   {
   	AccountNumber = "ACME123456789",
   	AccountTypeID = 1,
   	CPNIInformation = new CPNIInformation
   	{
   		AccountPassword = "password",
   		AuthorizedUserInformation = new AuthorizedUserInformation
   		{
   			new AuthorizedUserInformationItem { FirstName = "Elmer", LastName = "Fudd" }
   		},
   		SecurityQuestionID = "15",      //This must be a valid ID in your Core DB
   		SecurityQuestionAnswer = "SQA 1"
   	},
   	CustomerName = "Bugs Bunny",
   	PrimaryCustomerContact = new ContactInformationItem
   	{
   		FirstName = "Bugs",
   		LastName = "Bunny",
   		Street1 = "1 Main Street",
   		City = "Victor",
   		State = "NY",
   		ZipCode = "14564",
   		Country = "USA"
   	},
   	PrimaryCustomerContactSameAsBillingContact = true,
   	CustomerType = CustomerType.Billable,
   	AccountStatusID = 1,                //This must be a valid ID in your Core DB
   	MarketID = 2,                       //This must be a valid ID in your Core DB
   	BillCycleID = 1,                    //This must be a valid ID in your Core DB
   	BalanceAgingGroupID = 10001,        //This must be a valid ID in your Core DB
   	FinanceGroupID = 10001,             //This must be a valid ID in your Core DB
   	AccountReceivableGroupID = 10001,   //This must be a valid ID in your Core DB
   	ReportGroupID = 10002               //This must be a valid ID in your Core DB
   };
   

   Please note that some values are specific to your environment and should be filled in based on data in your CoreDB.

5. Create a CreateCustomerRequest object using the Requestor and Req objects from steps 1 & 4 . This object acts as an envelope for the entire request. Each operation in the Customer web service will have an associated request object (i.e. ModifyServiceRequest, ModifyCustomerRequest, etc.)

   //Create a request wrapper
   CreateCustomerRequest request = new CreateCustomerRequest(requestor, req);
   

6. Use the channel created in step 3 to make the Create Customer Request with the CreateCustomerRequest object.

   //submit the request
   CreateCustomerResponse response = channel.CreateCustomer(request);
   

This request will return a CreateCustomerResponse object with the results of the request. If any errors or issues occurred with the request the Messages property of the response will contain any error information. Below is a basic example of error handling from the call.

//Parse any error messages
if (response.Messages != null)
{
	Console.WriteLine("The following errors have occurred:");
	foreach (var msg in response.Messages)
	{
		Console.WriteLine(msg.MessageMember);
	}
}
else
{
	Console.WriteLine("No errors occurred.");
}

Querying a Customer OData

Tabular data queries are made using OData standard calls to the respective web services. Our example uses Microsoft’s System.Data.Services.Client to connect to the OData end point. You will need to add this reference to your own project.

1. Create a URI with the URI to the OData end point you wish to query. OData endpoint URIs use the same base URI as the web service, but have /CoreDataService appended to the path.

   //Configure end point URI for data request
   Uri ODataURI = new Uri("https://api.qaeng.infodirections.com/customer/1X/OLB_WIRELESS_AUTOMATION/CoreDataService");
   
   //Create a data service context
   DataServiceContext context = new DataServiceContext(ODataURI);
   

2. IDI ODatas require a special Authorization header that includes a Simple Web Token (SWT) for Authentication. Data Services supports adding this during the SendingRequest event.

   //Add a pre-send event to insert the Authentication Header
   context.SendingRequest += new EventHandler(OnSendingRequest);
   

   This event obtains a SWT and inserts it into the Authorization header of the request.

   private static void OnSendingRequest(object sender, SendingRequestEventArgs e)
   {
   	//Obtain the Simple Web Token (SWT)
   	var swt = Utilities.CreateSWT();
   
   	// Add an Authorization header that contains an WRAP access token to the request.
   	string AuthHeader = string.Format("WRAP access_token={0}", swt);
   	e.RequestHeaders.Add("Authorization", AuthHeader);
   } 
   

   Creation of the SWT is beyond the scope of this example, but a utility is included in the Utilities.cs for the purpose of this example.

3. Use a DataServiceQuery object to build a query request from the DataService Contact object. Use the name of the OData endpoint as the parameter for this call.
   You will also need to construct a local object for Data Services to deserialize the response to. This object should match the properties outlined in the CoreData documentation. An example of CustomerContact is included in the sample project.

   //This is the CustId in the Core database for the accout you wish to query it's contacts
   string CustomerID = "36532";
   
   //Create a query request and add a filter for CustomerID           
   DataServiceQuery dsq = context.CreateQuery("CustomerContact")
   	.AddQueryOption("$filter", "CustomerID eq " + CustomerID);
   

   Additional guidance on constructing local objects can be found in the metadata provided by the OData service by pasting
   https://api.idibilling.com/customer/1X/{YOUR_ENVIRONMENT}/CoreDataService/$metadata into your browser.
   Filtering is accomplished with the .AddQueryOption method. This method uses OData syntax to apply filters to your request. These methods can be strung together for multiple filters.

4. Execution of the request requires a call to the .Execute() method on the DataServiceQuery object and the results should be cast to a QueryOperationResponse object. The object contains a list of result items that should be cast to the local object you created for deserialization.

   //Execute the request
   QueryOperationResponse queryOperationResponse = dsq.Execute() as QueryOperationResponse;
   
   //Enumerate the response 
   List results = new List();
   foreach (CustomerContact dataEntity in queryOperationResponse)
   {
   	results.Add(dataEntity);
   	Console.WriteLine(dataEntity.CustomerName + "," + dataEntity.Street1 + "," + dataEntity.City);
   }
   

Using The Sample Application

When loading the IDISoapExamples application for the first time you will need to configure it for your environment. Properties specific to your web services environment will be marked with double brackets. For instance:

trustFactory.Credentials.UserName.Password = “{{YOUR PASSWORD}}”;

If you have configured your sample application correctly you should expect an output like the one below:

A list of contacts (ContactID, CustomerName, Street1, City) associated with the CustomerID is provided along with a Create Customer result. Any execution errors should appear in their stead.

Code Sample Project

The C# sample project which includes the examples above can be downloaded from the link below:
Getting Started with IDI SOAP Web Services Sample Project