Synergetic Custom Web Service API - How to create custom web service API

Overview

This document provides information on how to create custom web service APIs in order to communicate with Synergetic Databases.
SynAPI works with SQL Server Stored Procedures- users can create custom stored procedures or utilise existing Synergetic database stored procedures. 
SynAPI provides a capability to track version numbers for like web service methods to cater for different parameters and outputs.
Web Service Methods must be reviewed and authorised by Synergetic prior to publishing live to internal users or third party vendors. This is so that inadvertent mistakes can be avoided and best practices observed.

Requirements

Following Synergetic products are required to create Web Service Methods.

1. SynAPI – v01.00+ must be using SSL
2. Synergetic v65+
3. SynWeb 05.00+

User will also need internal Synergetic SQL Server access to create / modify user stored procedures. Please note all web service related stored procedures will be executed under SQL Server Application Role 'SynWebService' and not under user account directly.

Configuring Synergetic.xml file used by SynWeb and SynAPI

The following web service settings are added to the Synergetic.xml file. To modify these settings in Synergetic.xml file please go to SynWeb installation directory -> bin folder -> Run Synergetic.Application.SynWebCreateConfig.exe. Please note if you change settings other than those listed this may result into SynWeb errors.

Web Service Method Planning

Before you create new web service method, document your requirements:

1. Requirement - what's the purpose of this web service method?
   1. E.g. Get Synergetic community details – name as UGetCommunityDetails

(Name must be prefixed with capital 'U' to distinct user/client web service methods and Synergetic standard web service methods)

1. Inputs - what input parameters will be passed when calling?
   1. E.g. ID, Surname, Given1
2. Outputs - what outputs are required?

   1. E.g. ID, Title, Surname, Given1, Preferred, Email Address, Mobile Phone number and Address

      You will need to have a least one output value. If not a data set, this may be a unique identifier, a success/fail message, or otherwise something benign to that effect.

3. Stored Procedure – can I use existing Synergetic stored procedure or do I need to create my own stored procedure based on custom / existing tables?
   1. E.g. For above scenario I can use existing stored procedure 'spsCommunitySimple' which accept @CommunityName parameter and I can pass id, surname, given1 or barcode value to search for matching community records.
4. Permissions – Finally you will need to grant EXECUTE permission on selected stored procedure SQL Server Application Role 'Synergetic_SynAPI_dbo_ReservedDBRole'
   1. GRANT EXECUTE ON uspuStaffAddressiChrisHome to Synergetic_SynAPI_dbo_ReservedDBRole

How to create new Web Service Method?

Security Requirements: SYS -> CustomWebServiceMaint
There are three steps involved in creating Web Service Method; all these steps can be done through SynWeb interface.

1. Create Web Service Method
2. Send Authorisation request to Synergetic
3. Test Web Service Method

Create Web Service Method

The following provides details on how to create new web service method which can be accessed by third party vendors. In below documentation we will consider example we used during web service method planning from above details

1. Go to SynWeb -> System -> Web Service Maintenance and click 'Create New Web Service' button to start new web service create wizard
   
   
   
   
2. Enter below Web Service details and click Next button
   1. Method Name (must start with capital 'U')
   2. Method summary – purpose of this web service for documentation purpose
3. Active Flag – active by default, can be marked as inactive if not required in future
   
   
   
   
4. Enter Web Service version details and click Next button
   1. Version No – by default 1, you can create multiple version for same web service method if you change input / output parameters and you would like to have multiple version of same method
   2. Database Name – Synergetic database you accessing information from
   3. Stored Procedure Name – You will see list of stored procedures from the selected database where the 'SynWebService' application role has execute permission to. If you don't see your stored procedure in the dropdown list then possibly you haven't granted execute permission to 'SynWebService' application role or other possibility your stored procedure is created in wrong database.
      
      
      
      
5. Select Web Service parameters and click Next button
   1. Checkboxes – Check the checkbox for parameter you required. You might see many extra parameters used by Synergetic but you can ignore those and select one relevant to your requirements
   2. Default Value – You can pass default value for parameter, this value will be applied if web service calling user don't pass parameter.
   3. Description – Parameter description for documentation purpose. E.g. CommunityName – Enter community ID, Given1 or Surname
   4. Read Only – You can mark parameter as read only if you don't want end user to pass value externally, generally this is useful when you specify default value and don't want end user to pass value.
      
      
      
      
6. Select Web Service XML Output columns and click Next button
   1. Checkboxes – Check the checkbox for columns you required. You might see many extra columns but you can ignore those and select one relevant to your requirements
      
      
      
      
7. Review Web Service summary and click Finish button to complete creation process. This will redirect back to Web Service Maintenance page.
   
   
   
   
8. You can edit web service method version details by clicking Edit icon or you can delete by clicking Delete icon from the grid

Send Authorisation request to Synergetic

Once Web Service Method is created then you will need to send it to Synergetic for authorisation purpose. Synergetic will record all web service related data for licensing purpose and will review stored procedure you are using. During authorisation process Synergetic might advise you to change stored procedure if any issues found with code or if SQL best practice is not followed.

For authorisation process Synergetic expose web services APIs, this APIs are already integrated with SynWeb and all process managed seamlessly via interface. Follow below steps to request authorisation from Synergetic.

1. Click 'X' button from Web Service Versions grid -> Authorised column as circled in below screen shot. After you sent authorisation request, when you mouse over the 'X' button tooltip will provide information about when you sent authorisation request last time.
   Please note if you change any details, you will need to resend authorisation request to Synergetic.
   
   
   
    
   
   
2. Wait for Synergetic to approve your request. Once your request is approved, you will receive an email from Synergetic about authorisation status changed. After your request is approved you can click 'Synchronise Authorisation' button to synchronise authorisation details. If not authorised then follow instruction in email about next step. After authorisation details are synchronised with Synergetic icon will changed green ticked
   
   
   
   
3. If you change any details, your web service will be suspended and you will need to resend an authorisation request to Synergetic. Once you resend authorisation request to Synergetic, wait for approval email as per step 2. Warning icon will appear under Authorisation column until you synchronise authorisation details from Synergetic after approval.
   
   

Test Web Service Method

Once Web Service is authorised by Synergetic, third party vendor can call your web service. Below information will require when calling web services, it's recorded in SQL table called 'SynergeticTrustedVendors'. Synergetic will provide this information and if multiple third party vendors will be using your web services then please ask Synergetic to enter records for all vendors.

1. Web Service Address. E.g. https://synapi.schools.edu.au/SynergeticWcfService.svc
2. Vendor Token GUID
3. Vendor Password

You can test web service using Web Service Testing tool provided by Synergetic.

1. Go to SynWeb -> System -> Test Web Service
2. Fill details requested in above points a, b & c
3. Select Web Service Method Name and Version No to test
4. Fill out value for all Parameters and then click Execute button to get web service response

Developers Guide – API Documentation

Below documentation provides information required by developers who want to call SynAPI to integrate third party products with Synergetic.

Web Service Request and Response parameters

Below Input and Output parameters are available by Synergetic Web Service API. This information will be required by any third party vendor who calls Synergetic web services.

WebServiceInputParameter - Complex type, below values are required

WebServiceOutputParameter

Available Web Service Methods

Synergetic generate XML level documentation for all custom Web Service Methods created by school. You can use third party custom tools to generate help document in .html or .chm format from xml file.

1. Go to SynWeb -> System ->Web Service Maintenance web page and click 'Download Help Document' button.
   
   
   
   
2. Save SynAPIHelp.xml file.
   
   

Testing the SynAPI Externally

A good technique to completely test the SynAPI is to use a third party API calling tool (such as SoapUI) and run it on a laptop or a machine that is NOT on the school's network.

Here is an example below of a SoapUI call to a school's SynaPI Web service with some input parameters - and the resultant output from the API

and here is a copy of the soapui project (that can be imported into SoapUI). Please note this SoaupUI won't work and is only for informative/dev assistance purposes (because it refers to a fake school url and does not have correct VendorGuids and VendorPaswords in it):  

In soap ui - you can create project:

Choose add WSDL:

And then enter your externally accessible URL here:

This will import all available endpoints

An example payload - please pay attention on the case sensitivity of <arr:Key> 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="https://synapi.synergetic.net.au/66-80-01" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Header/>
	<soapenv:Body>
		<ns:RunWebServiceMethod>
			<!--Optional:-->
			<ns:inputParameter>
				<ns:ParameterList>
					<!--Zero or more repetitions:-->
					<arr:KeyValueOfstringanyType>
						<arr:Key>surname</arr:Key>
						<arr:Value xsi:type="a:string" xmlns:a="http://www.w3.org/2001/XMLSchema">Smith</arr:Value>
					</arr:KeyValueOfstringanyType>
				</ns:ParameterList>
				<!--Optional:-->
				<ns:SourceIP/>
				<!--Optional:-->
				<ns:TenantCode/>
				<!--Optional:-->
				<ns:VendorPassword/>
				<!--Optional:-->
				<ns:VendorTokenGuid/>
				<!--Optional:-->
				<ns:WebServiceMethodName>UCantTouchThis</ns:WebServiceMethodName>
				<!--Optional:-->
				<ns:WebServiceMethodVersionNo>1</ns:WebServiceMethodVersionNo>
			</ns:inputParameter>
		</ns:RunWebServiceMethod>
	</soapenv:Body>
</soapenv:Envelope>

Please note some characters may need to escaped (XML wise):

"   "
'   '
<   &lt;
>   &gt;
&   &amp;