Tamarac Bulk Report API Overview
Tamarac Bulk Report API Overview
January 25, 2016
Contents Introduction ................................................................................................................................................................. 1 Basic Setup .................................................................................................................................................................. 1 Core Service Methods ................................................................................................................................................. 6 SubmitBulkReportRequest ............................................................................................................................................ 6 CheckJobStatus ............................................................................................................................................................... 7 DownloadFile ................................................................................................................................................................... 8
i
Introduction The Tamarac bulk report API is an http-based web service which allows you to automatically generate and retrieve bulk reports via customized client applications. Communication with the service is secured at the transport layer via SSL, and authentication is performed in the message layer, with the same user name and password combinations used to sign into Advisor View or Advisor Rebalancing. This document describes creating a basic client application using Microsoft .NET, C#, and Visual Studio 2013, and includes an overview of all of the methods and properties of the API. The web service itself is a WCFbased service, which is also a Microsoft technology. However, communication with the service can be completed via any platform in which http messages can be sent and received, such as Java. A working sample application, including the source code in a Visual Studio solution, is available from Tamarac. This document assumes prior expertise in developing applications using Microsoft .NET, C#, and Visual Studio 2013.
Basic Setup 1. Create a new application in Visual Studio 2013 (or open an existing application which will be used to call the Tamarac bulk report API). Any application type can be used, such as web, desktop, or service applications. For this example, we’ll create a basic Windows Forms application, to mimic the completed sample application solution.
2. Add a button to Form1, and double-click it to add an event handler in the C# code. For brevity, this document won’t cover creating user interface elements beyond a single button, and we’ll use the event handler for this button to add code and invoke the service.
1
3. Right-click the References node in the Solution Explorer and select Add Service Reference (adding a service reference in Visual Studio is the simplest way to set up communications with the Tamarac web service). You will now see the Add Service Reference dialog. 4. In the Address box, enter the following service URL: https://services.tamaracinc.com/bulkreportexternalapi/TamaracReportService.svc. 5. Click Go. You will see that Visual Studio contacts the Tamarac servers and discovers metadata about the web service.
2
6. Give the service reference a descriptive namespace, such as “TamaracBulkReportService”, and click OK on the dialog. You will see that the reference has been successfully added in the solution explorer.
7. Also note that configuration for the reference, such as the service URL, has been added to the application configuration file.
3
8. Return to the Form1.cs file. Add a using statement for the service reference namespace.
The service exposes the following basic methods, which can be invoked from your client code. •
TestConnection
•
SubmitBulkReportRequest
•
GetJobStatus
•
DownloadFile
The basic sequence to interact with the service is: a.
Call SubmitBulkReportRequest, passing the necessary arguments. This method is asynchronous on the service side – meaning it will return immediately – and meanwhile the bulk report generation will be in process.
b.
Call GetJobStatus one or more times, until the service indicates that the job has either succeeded or failed.
c.
If success is indicated by the GetJobStatus method, the DownloadFile method can be invoked to retrieve the file.
4
9. To begin, we’ll add a call to the TestConnection method. This can be used during development to test that the connection between your client code and the Tamarac service is operating properly, including the authentication. 10. Add code to the button1_click event handler as follows, substituting a valid username and password.
Note that all invocations of the service methods begin the same way. An instance of the service client is created, and the ClientCredentials property is set appropriately. 11. Press F5 to run the application. Click the button. •
If communication is successful, including a valid username and password, the following message will be displayed, containing the email address associated with the login.
•
If an invalid username/password combination is used, the service will refuse the connection at the protocol level, resulting in a non-specific exception message at the client.
You’ve now successfully created a basic client application. You can proceed as necessary with adding code to call the other service methods to generate bulk reports.
5
Core Service Methods In this section, we’ll discuss the three core service methods:
•
SubmitBulkReportRequest
•
CheckJobStatus
•
DownloadFile.
Web service URL: https://services.tamaracinc.com/bulkreportexternalapi/TamaracReportService.svc.
SubmitBulkReportRequest This method accepts an instance of the TamaracBulkReportRequest object. The following properties can be set to specify the details of the bulk report being requested.
Property
Description
PrimaryApplication
• • •
Required. Must be set to an enumeration value from the ApiApplication enumeration shown above. Indicates the application in which the bulk report being requested has been configured.
ReportName
• • •
Required. The name of the bulk report being requested. Should match the name of a bulk report configured in the web site for the product identified with the PrimaryApplication property.
AccountNumbers
• •
Optional. Identifies the accounts whose data should be included in the bulk report. If not specified, all accounts to which the username has access will be included.
•
6
AccountSetName
•
Not applicable to bulk reports which do not contain account information, such as Security Information reports.
• •
Optional. Should match the name of an account set configured in the web site for the product identified with the PrimaryApplication property. Not applicable to bulk reports which do not contain account information, such as Security Information reports.
•
SavedSearchName
• • •
SubmitBulkReportRequest
•
Optional. Should match the name of a saved account search configured in the web site for the product identified with the PrimaryApplication property. Not applicable to bulk reports which do not contain account information, such as Security Information reports. Returns a jobId, which is a GUID string that is used for the following two service calls.
CheckJobStatus This method accepts the jobId returned from the SubmitBulkReportRequest method. It returns information about the asynchronous report generation status, represented by the types below.
7
Property
Description
JobStatusResponse_ErrorMessage
•
Will contain an error message if conditions prevented the job status from being retrieved (such as entry of an invalid GUID for the jobId).
JobStatusResponse_JobStatus
• •
Holds information about the job status. Will be empty if JobStatusResponse.ErrorMessage is present. IsCompressed:
•
• •
•
StatusType •
•
Will be true if the generated bulk report file is in ZIP format, otherwise false. Larger reports are automatically compressed into ZIP format, regardless of the Compress checkbox setting from the bulk reports page in Advisor View or Advisor Rebalancing.
Will be set to one of the following values: Started, Succeeded, Failed, Unknown.
Message •
If the StatusType is error, this property will contain a description of the error.
DownloadFile This method accepts the jobId string, plus a Boolean value (formatAsXml) indicating whether the service should transform the bulk report file to XML before download. It returns a stream which can be used to retrieve the file bytes from the service. It is important to note that this method produces a streamed response, in contrast to the typical, fully buffered response message of most web service methods, including the other methods of the Tamarac bulk reporting API. The completed sample application includes code showing how to consume a streamed response in a client application. The response must be read to a destination buffer-by-buffer until the last byte is read. For example:
8
Make sure when you save the file to the local file system on the client, you save it with the correct file extension, or else note the format of the downloaded file. The default file format depends on whether the file is compressed:
•
If the GetJobStatus method indicates the file is compressed, the downloaded file will always be in ZIP format. The file inside of the ZIP will be either CSV or XML, depending on the value passed to the formatAsXml parameter.
•
If the GetJobStatus method indicates the file is not compressed, the downloaded file will be either CSV or XML, depending on the value passed to the formatAsXml parameter.
9
January 25, 2016
Contents Introduction ................................................................................................................................................................. 1 Basic Setup .................................................................................................................................................................. 1 Core Service Methods ................................................................................................................................................. 6 SubmitBulkReportRequest ............................................................................................................................................ 6 CheckJobStatus ............................................................................................................................................................... 7 DownloadFile ................................................................................................................................................................... 8
i
Introduction The Tamarac bulk report API is an http-based web service which allows you to automatically generate and retrieve bulk reports via customized client applications. Communication with the service is secured at the transport layer via SSL, and authentication is performed in the message layer, with the same user name and password combinations used to sign into Advisor View or Advisor Rebalancing. This document describes creating a basic client application using Microsoft .NET, C#, and Visual Studio 2013, and includes an overview of all of the methods and properties of the API. The web service itself is a WCFbased service, which is also a Microsoft technology. However, communication with the service can be completed via any platform in which http messages can be sent and received, such as Java. A working sample application, including the source code in a Visual Studio solution, is available from Tamarac. This document assumes prior expertise in developing applications using Microsoft .NET, C#, and Visual Studio 2013.
Basic Setup 1. Create a new application in Visual Studio 2013 (or open an existing application which will be used to call the Tamarac bulk report API). Any application type can be used, such as web, desktop, or service applications. For this example, we’ll create a basic Windows Forms application, to mimic the completed sample application solution.
2. Add a button to Form1, and double-click it to add an event handler in the C# code. For brevity, this document won’t cover creating user interface elements beyond a single button, and we’ll use the event handler for this button to add code and invoke the service.
1
3. Right-click the References node in the Solution Explorer and select Add Service Reference (adding a service reference in Visual Studio is the simplest way to set up communications with the Tamarac web service). You will now see the Add Service Reference dialog. 4. In the Address box, enter the following service URL: https://services.tamaracinc.com/bulkreportexternalapi/TamaracReportService.svc. 5. Click Go. You will see that Visual Studio contacts the Tamarac servers and discovers metadata about the web service.
2
6. Give the service reference a descriptive namespace, such as “TamaracBulkReportService”, and click OK on the dialog. You will see that the reference has been successfully added in the solution explorer.
7. Also note that configuration for the reference, such as the service URL, has been added to the application configuration file.
3
8. Return to the Form1.cs file. Add a using statement for the service reference namespace.
The service exposes the following basic methods, which can be invoked from your client code. •
TestConnection
•
SubmitBulkReportRequest
•
GetJobStatus
•
DownloadFile
The basic sequence to interact with the service is: a.
Call SubmitBulkReportRequest, passing the necessary arguments. This method is asynchronous on the service side – meaning it will return immediately – and meanwhile the bulk report generation will be in process.
b.
Call GetJobStatus one or more times, until the service indicates that the job has either succeeded or failed.
c.
If success is indicated by the GetJobStatus method, the DownloadFile method can be invoked to retrieve the file.
4
9. To begin, we’ll add a call to the TestConnection method. This can be used during development to test that the connection between your client code and the Tamarac service is operating properly, including the authentication. 10. Add code to the button1_click event handler as follows, substituting a valid username and password.
Note that all invocations of the service methods begin the same way. An instance of the service client is created, and the ClientCredentials property is set appropriately. 11. Press F5 to run the application. Click the button. •
If communication is successful, including a valid username and password, the following message will be displayed, containing the email address associated with the login.
•
If an invalid username/password combination is used, the service will refuse the connection at the protocol level, resulting in a non-specific exception message at the client.
You’ve now successfully created a basic client application. You can proceed as necessary with adding code to call the other service methods to generate bulk reports.
5
Core Service Methods In this section, we’ll discuss the three core service methods:
•
SubmitBulkReportRequest
•
CheckJobStatus
•
DownloadFile.
Web service URL: https://services.tamaracinc.com/bulkreportexternalapi/TamaracReportService.svc.
SubmitBulkReportRequest This method accepts an instance of the TamaracBulkReportRequest object. The following properties can be set to specify the details of the bulk report being requested.
Property
Description
PrimaryApplication
• • •
Required. Must be set to an enumeration value from the ApiApplication enumeration shown above. Indicates the application in which the bulk report being requested has been configured.
ReportName
• • •
Required. The name of the bulk report being requested. Should match the name of a bulk report configured in the web site for the product identified with the PrimaryApplication property.
AccountNumbers
• •
Optional. Identifies the accounts whose data should be included in the bulk report. If not specified, all accounts to which the username has access will be included.
•
6
AccountSetName
•
Not applicable to bulk reports which do not contain account information, such as Security Information reports.
• •
Optional. Should match the name of an account set configured in the web site for the product identified with the PrimaryApplication property. Not applicable to bulk reports which do not contain account information, such as Security Information reports.
•
SavedSearchName
• • •
SubmitBulkReportRequest
•
Optional. Should match the name of a saved account search configured in the web site for the product identified with the PrimaryApplication property. Not applicable to bulk reports which do not contain account information, such as Security Information reports. Returns a jobId, which is a GUID string that is used for the following two service calls.
CheckJobStatus This method accepts the jobId returned from the SubmitBulkReportRequest method. It returns information about the asynchronous report generation status, represented by the types below.
7
Property
Description
JobStatusResponse_ErrorMessage
•
Will contain an error message if conditions prevented the job status from being retrieved (such as entry of an invalid GUID for the jobId).
JobStatusResponse_JobStatus
• •
Holds information about the job status. Will be empty if JobStatusResponse.ErrorMessage is present. IsCompressed:
•
• •
•
StatusType •
•
Will be true if the generated bulk report file is in ZIP format, otherwise false. Larger reports are automatically compressed into ZIP format, regardless of the Compress checkbox setting from the bulk reports page in Advisor View or Advisor Rebalancing.
Will be set to one of the following values: Started, Succeeded, Failed, Unknown.
Message •
If the StatusType is error, this property will contain a description of the error.
DownloadFile This method accepts the jobId string, plus a Boolean value (formatAsXml) indicating whether the service should transform the bulk report file to XML before download. It returns a stream which can be used to retrieve the file bytes from the service. It is important to note that this method produces a streamed response, in contrast to the typical, fully buffered response message of most web service methods, including the other methods of the Tamarac bulk reporting API. The completed sample application includes code showing how to consume a streamed response in a client application. The response must be read to a destination buffer-by-buffer until the last byte is read. For example:
8
Make sure when you save the file to the local file system on the client, you save it with the correct file extension, or else note the format of the downloaded file. The default file format depends on whether the file is compressed:
•
If the GetJobStatus method indicates the file is compressed, the downloaded file will always be in ZIP format. The file inside of the ZIP will be either CSV or XML, depending on the value passed to the formatAsXml parameter.
•
If the GetJobStatus method indicates the file is not compressed, the downloaded file will be either CSV or XML, depending on the value passed to the formatAsXml parameter.
9
