Getting Started with Web Services 2.0

Additional Resources

1. Introduction to Projector Web Services webinar is a great resource providing an introduction to Projector's web services and highlighting some examples of its use.

2. Watch the Projector Web Services Webinar to learn about the APIs provided by Projector and best practices around their use.

Before using web services there are a few areas you should become familiar with.

Permissions

For new users of web services, this is the area where most mistakes are made. Often developers don't have a full understanding of Projector's permission structure. If you are a developer you should work with your Projector administrator to ensure you have the correct permissions. To do this you should spec out what you want to accomplish via web services. Then work with your administrator to find out which permissions are required to perform each action. At a minimum you will need the following:

  • Web services module enabled (there may be a cost associated with this).
  • user account. In general you should try and create a special user account named 'web services' for this rather than use your own. This is because Projector keeps logs of who changed what in the system. You would want to know whether something was changed via web services or via manual entry.
  • The web services global permission set to View or Update. This gives you permission to access the web services, but not necessarily to do anything.
  • The export data global permission. This gives you permission to retrieve data out of Projector. You probably want this turned on.
  • Other permissions. Using web services grants you no greater permissions than your normal user settings. So if you cannot create projects logged in as the user, then you will not be able to create projects via web services. You will need appropriate global permissions and cost center permissions for everything you want to do via web services. Please discuss your development objectives with your Projector administrator to determine what permissions you will need. 

Sandboxes

Sandboxes are test environments of your production installation. I cannot stress enough that using sandboxes during implementation and testing of your web services is extremely important. If mistakes are made that mess up your production environment then you will be responsible for cleaning it up. You can read more about sandboxes and how to obtain one here.

Web Services 1.0

There are a set of legacy web services available. These will eventually be supplanted by a newer set of web services based on Web Services 2.0. As not all the functionality of the old web services has been implemented in the newer version, you should review that documentation to find which services can best solve your programming requirements. The 1.0 web services will continue to be supported by Projector.

RESTful Web Services

Projector offers some RESTful web services. Please see the Report Web Services for more information.

Authentication

Please see the C Sharp Example for important information on how to properly connect to web services.

WSDL

The web services descriptor can be found at this url - https://secure.projectorpsa.com/OpsProjectorWcfSvc/PwsProjectorServices.svc?wsdl

If you want a single WSDL file you can use - https://secure.projectorpsa.com/OpsProjectorWcfSvc/PwsProjectorServices.svc?singleWsdl

Passing Parameters to SOAP Calls

When creating your requests, please don't pass in optional parameters as empty. For instance

<UTCOffset></UTCOffset>

Projector may interpret the data type incorrectly and cause a server error. Instead, omit it from the xml request. Do not use the fingerprint parameter. This is for internal Projector use only.

Error Handling

Your code should try and catch exceptions. In the error handler please log the request and response XML. This can then be sent to Projector support to expedite investigation of any problems. See the Support section below for more information.

Support

You can send in questions to the support desk. However the support desk does not consist of software developers. So the team may not be able to answer all of your software development questions. If you need more in depth help than the support desk can provide then you may be referred to our consulting team discussed below. When submitting support tickets please:

  1. Check that your permissions are correct
  2. Test whether you can perform the requested action through the UI instead.
  3. Include which user account is connecting - typically an email address.
  4. Include which installation you are connecting to - typically production or sandbox.
  5. Request XML
  6. Response XML

If you don't know how to get the request and response XML out of your development environment then you can install a program called Fiddler. This program allows you to decrypt https traffic and inspect the requests and responses from Projector.

Consulting

New users to web services are highly advised to obtain consulting from our development staff. This ensures that what you want to accomplish is possible, you understand how to implement it properly, and you understand all the ramifications of your implementation. In addition, if you need assistance in how to develop your web services beyond what the support desk can provide, our team of software development professionals with decades of experience can assist you. If you would like consulting services please ask your Projector administrator to contact the sales department.

Example Code

There is example C# code on the C Sharp Example page.