SOAP Web Services Core Concepts

Workflow

An example workflow for processing data in a space would look like this:

Login > publishData > isJobComplete > getJobStatus > Logout

All operations occur within a single session that is initiated with a call to Login and ends with a call to Logout.

Login and Login Tokens

On Login, the program provides the user name and password of an Administrator and receives a login token. This token is passed in all subsequent method calls, and is analogous to the Administrator logging into the system via a web browser. Note: A proxy user can be used in the login call the same way as anormal browser-based login.

Most commands return a string token that is passed to subsequent commands. For example, publishData returns a token that is passed to isJobComplete to determine whether processing data in the space is done. This check allows this example program to process multiple spaces independently and confirm that processing is complete before starting another.

Once Logout has been called, the Login token is no longer valid and any additional call will fail.

A Login token stays valid until either:

  • Logout
  • The server restarts
  • It is not used for more than 10 minutes

Job Tokens

Many services return job tokens that are used by subsequent services within a login session.

Space IDs

Any command that is space-specific requires a space ID as a parameter. The space ID is in the form:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

where x is any hexadecimal value (0-9, a-f).

You can find a space ID by going to Admin - Manage Space - Modify Properties.

Upload Limit

There is no specific file limit size for uploading via web services. However, for larger files we recommend uploading in chunks.

Requirements

Cookies

Birst uses cookie-based load balancing so Birst Web Services requires applications to support session cookies.

If you receive errors related to invalid login tokens after the login operation, this is due to your web service application not supporting session cookies. Note: Currently Birst has multiple cookies, so your application must support more than one cookie.

HTTPS/TLS

Birst uses HTTPS with TSL 1.2.

User Accounts

There are a few requirements on the use of the Birst Web Services:

  • All of the operations, unless otherwise noted, require the logged in user to be a Space Administrator for space-specific commands, or an Account Administrator for account-specific commands.
  • The loged in user must have the Web Services product. Go to Home - UserName - Settings and verified that the Features list includes Web Services. If it does not, contact your Infor representative.

Known Issues

With the exception of exportReportToPDF and exportReportToXLS, the exportReportTo web services are not supported for Visualizer reports.

WSDL Location and Additional Documentation

The Web Services Description Language (WSDL) is release-specific. The documentation for the web services supported on the server can be found here.

https://<birst-endpoint>/CommandWebService.asmx

For example, https://login.bws.birst.com/CommandWebService.asmx.