Connecting to the Cobra Web Service Host

Connect to the Web Service host in order to use the Cobra Web Service and create applications that can execute Cobra functionalities over the network.

The first step in using the ClientAPI is to create an instance of the CobraServices class. This is a root class that consumes the Cobra Web Service host. You can construct this class the same way you normally create an object from a class by using the new keyword. For example:

CobraServices cobraServices = new CobraServices();

Authenticating Cobra

The Cobra Web Service supports native and Windows authentication.

Providing Cobra Username, Password, and Data Source

If Cobra is configured to use native authentication, you need to define the Cobra user on the instance of the CobraServices class. The user can be specified in the ServiceIdentityData property. Cobra username must be specified on the ServiceIdentityData.Username property. The password must be defined in the ServiceIdentityData.SecurePassword property that can be achieved in two ways:

• Initialize an instance of SecurePassword class using a SecureString object that contains the password. For more information about SecureString class, refer to MSDN documentation.
• Initialize an instance of SecurePassword class and call the AppendChar(char) method to append each character of the password. For example:

If Cobra is configured in a standalone or server-deployment environment and has multiple data sources, the data source must be specified on the ServiceIdentityData.DataSourceKey property.

cobraServices.ServiceIdentityData.Username = "SYSADMIN";
cobraServices.ServiceIdentityData.SecurePassword = new SecurePassword();
cobraServices.ServiceIdentityData.SecurePassword.AppendChar('p');
cobraServices.ServiceIdentityData.SecurePassword.AppendChar('a');
cobraServices.ServiceIdentityData.SecurePassword.AppendChar('s');
cobraServices.ServiceIdentityData.SecurePassword.AppendChar('s');
cobraServices.ServiceIdentityData.SecurePassword.AppendChar('w');
cobraServices.ServiceIdentityData.SecurePassword.AppendChar('o');
cobraServices.ServiceIdentityData.SecurePassword.AppendChar('r');
cobraServices.ServiceIdentityData.SecurePassword.AppendChar('d');
cobraServices.ServiceIdentityData.DataSourceKey = "COBRA";

Note: The ServiceIdentityData.Password property has been marked as obsolete because using this property allocates the password in the heap memory that can be inspected using third party tools and represents a security issue. It is highly recommended to use the ServiceIdentityData.SecurePassword property instead.

Authenticating Windows

If Cobra is configured to use Windows Authentication, you do not need to supply the Cobra username and password to the ServiceIdentityData property on the instance of CobraServices class. The Cobra Web Service ClientAPI automatically transfers your Windows credentials to the Cobra Web Service host. The Cobra Web service host uses the Windows credentials as the Cobra user.

Attention: See Turn Windows Authentication On or Off.

You still need to supply the data source on the ServiceIdentityData.DataSourceKey property in the instance of CobraServices class if Cobra is configured in a standalone or server-deployment environment and has multiple data sources.

Calling the Login Operation to Connect to the Cobra Web Service Host

Since the CobraServices class is responsible in consuming the Cobra Web Service host, the instance of the class should be connected to the Cobra Web Service before you could perform some Cobra actions like running Advance Calendar, Calculate Progress, or Calculate Forecast. To connect to the Cobra Web Service, you must invoke the Login method. For example:

LoginResult loginResult = cobraServices.Login();

This will always be true in the current version of Cobra Web Service. The LoginResult class also contains a String property named ErrorMessage, which currently is always empty.

The Login method returns an instance of LoginResult class that contains a Boolean property named Success. The Success property determines if the Login method succeeds. In the current version of the Cobra Web service, this will always be true. In the future version, the value of this property will identify whether the Cobra user is valid or not. The LoginResult class also contains a String property named ErrorMessage. In the future versions, this will contain the error messages and the causes of validation failures.

To be compatible in the future version, it is recommended to check for the value of these properties before doing any Cobra actions. For example:

if (loginResult.Success) {
// Run processes here.
}
else {
MessageBox.Show(loginResult.ErrorMessage, "Login Failed", MessageBoxButtons.Ok, MessageBoxIcons.Error);