Introduction to the Subscribe-HR API

From Subscribe-HR Wiki Help
Revision as of 01:46, 20 September 2018 by Wikihelp (Talk | contribs)

Jump to: navigation, search

Overview

The Subscribe-HR SOAP API provides a seamless way of accessing and updating information from third-party applications. The purpose of this document is to outline how to get started with the Subscribe-HR API. It will also outline code examples using the PHP programming language and provide enough information to authenticate, query and update data using standard API functions.

WSDL Access

In order to successfully make calls to the API, you will need to ensure that you have an active user account with Subscribe-HR with the “Allow API Accesses” flag set to Yes. User account permissions will determine which fields and objects can be accessed. For example, you will not be able to update field “First Name” under “Employee” object if you do not have these permissions assigned to your account. Also in a similar way, you will not be able to get data for “Gender” field if view permissions for that field are not assigned to your account. Please refer to Group Permissions section in the wiki to learn more about Subscribe-HR permission settings.

WSDL File Download

Once Access is setup obtain and consume WSDL file which can only be accessed once a user account is authenticated to Subscribe-HR. We suggest that you download and store WSDL file locally in your system instead of making remote calls to the URL due to added authentication complexity. To access the WSDL file follow the steps below.

  1. Login to your Subscribe-HR account.
  2. Paste the following URL to the location bar https://www.subscribe-hr.com/cb/app/hr/misc/?request=wsdl.

This is a unique WSDL file for your system. It will also include all client specific custom fields.

Enable Extra Objects to the WSDL

By default the WSDL file will only contain references to seven objects that are most frequently used in integration projects. If you require access to additional objects you can enable it in the development tool by following the steps below.

  1. Navigating to Development > Objects > Select an Object.
  2. Select Include In WSDL flag to Yes
  3. Select the Save button.

After accessing WSDL URL again you will notice that the object is now part of the definition.

Error Handling

Errors are handled using SOAP Fault and should be managed by SOAP client in the programming language of your choice. An example of SOAP fault is shown below. In the current version of the API we do not use any fault codes. It will just be set to “Subscribe” by default. Fault string will contain the appropriate error message.

<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> 

 <SOAP-ENV:Body>
   <SOAP-ENV:Fault>
     <faultcode>Subscribe</faultcode>
     <faultstring>Authentication failed because the username or password is invalid.</faultstring>
   </SOAP-ENV:Fault>
 </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Authentication

Authentication to the Subscribe-HR API is done by making a call to authenticate method with your account username and password. A session token is returned for your reference. Once authentication is complete your client object should maintain the session until such time as your application is done making calls to the API.

The authenticate method has the following format shown in the below table.

Item Explanation
authenticate(username, password) Generic format of authenticate method
username Subscribe-HR username
password Subscribe-HR password
return Session token


Request

<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:webservices.subscribe-hr.com"> 

 <SOAP-ENV:Body>
   <ns1:authenticate>
     <username>user@company.com</username>
     <apiKey>yourpassword</apiKey>
   </ns1:authenticate>
 </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:webservices.subscribe-hr.com"> 

 <SOAP-ENV:Body>
   <ns1:authenticateResponse>
     <authenticateResponse>m4fpkpjd5gpprecmhf8ldqi5e1</authenticateResponse>
   </ns1:authenticateResponse>
 </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Query Records

A call to the queryObject generic function can be made to retrieve information for any object in the system that is exposed in the WSDL. The call is made by passing object name and the condition. queryResponseObject is returned in the response and it contains record count and list of objects. The table below explains the features of the queryObject function.

Item Explanation
queryObject(object, condition) Generic format of query function
object Name of the system object (e.g. Employee or EmployeeAbsenceDetails).
condition Specific condition. Can be left blank. For example you may want to only retrieve a subset of records for a specific object (e.g. get all EmployeeAbsenceDetails records for one employee only) Supported conditional operators: >=, <=, <>, =, >, <, IN
return queryResponseObject.

Conditional Operators Matrix

The table below shows the conditional operator, the name of the condition and an example of the use of the condition in a query.

Condition Name Example
>= Greater or Equal To queryObject(“Employee”, “StartDate>=2009-06-17”)
<= Less or Equal To queryObject(“Employee”, “StartDate<=2009-06-17”)
>= Greater or Equal To queryObject(“Employee”, “StartDate>=2009-06-17”)
<> Not Equal To queryObject(“Employee”, “Id<>71”)
= Equal To queryObject(“Employee”, “Id=71”)
> Greater Than queryObject(“Employee”, “Id>71”)
<> Equal To queryObject(“Employee”, “Id=71”)
< Less Than queryObject(“Employee”, “Id<100”)
IN In a List queryObject(“Employee”, “Id IN (71, 72, 73)”)
AND And Condition queryObject(“Employee”, “Id IN (71, 72, 73) AND StartDate>=2009-06-17”)

Request

<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:webservices.subscribe-hr.com"> 

 <SOAP-ENV:Body>
   <ns1:queryObject>
     <object>Employee</object>
     <condition>Surname = Funaki</condition>
   </ns1:queryObject>
 </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:webservices.subscribe-hr.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 

 <SOAP-ENV:Body>
   <ns1:queryObjectResponse>
     <queryObjectResponse>
       <ns1:count>1</ns1:count>
       <ns1:objects xsi:type="ns1:Employee">
         <ns1:Id>74</ns1:Id>
         <ns1:Surname>Funaki</ns1:Surname>
         <ns1:FirstName>Loni</ns1:FirstName>
         <ns1:Appointed>1991-10-15T00:00:00</ns1:Appointed>
         <ns1:FirstAidRenewal>2013-10-16T00:00:00</ns1:FirstAidRenewal>
         <ns1:DateOfBirth>1947-11-22T00:00:00</ns1:DateOfBirth>
         <ns1:EyeTest>2013-10-15T00:00:00</ns1:EyeTest>
         <ns1:DateLeft xsi:nil="true"/>
         <ns1:LastDayofWork xsi:nil="true"/>
         <ns1:DriversLicence>true</ns1:DriversLicence>
         <ns1:DriversLicenceNumber>2312ed</ns1:DriversLicenceNumber>
         <ns1:EmploymentType>fulltime</ns1:EmploymentType>
         <ns1:EmployeeAgreedData>true</ns1:EmployeeAgreedData>
         <ns1:EmployeeAgreedDataDate>2010-06-01T00:00:00</ns1:EmployeeAgreedDataDate>
         <ns1:EmployerNotice>0</ns1:EmployerNotice>
         <ns1:EmployeeNotice>0</ns1:EmployeeNotice>
         <ns1:ExitInterviewDate xsi:nil="true"/>
         <ns1:ExitInterviewNotes><html/></ns1:ExitInterviewNotes>
         <ns1:EmailAddressHome xsi:nil="true"/>
         <ns1:EmailAddressWork>loni@work.com</ns1:EmailAddressWork>
         <ns1:FireWarden>true</ns1:FireWarden>
         <ns1:FirstAider>true</ns1:FirstAider>
         <ns1:Gender>female</ns1:Gender>
         <ns1:GlassesWorn>true</ns1:GlassesWorn>
         <ns1:HealthCheck>2009-10-21T00:00:00</ns1:HealthCheck>
         <ns1:Initials>L.F.</ns1:Initials>
         <ns1:IDCard>true</ns1:IDCard>
         <ns1:IDExpiryDate>2013-10-16T00:00:00</ns1:IDExpiryDate>
         <ns1:KnowAs xsi:nil="true"/>
         <ns1:KeyHolder>true</ns1:KeyHolder>
         <ns1:Leaver>false</ns1:Leaver>
         <ns1:MaidenName>Tilly</ns1:MaidenName>
         <ns1:ManagerReference xsi:nil="true"/>
         <ns1:Manager>true</ns1:Manager>
         <ns1:Mobile xsi:nil="true"/>
         <ns1:Nationality>australian</ns1:Nationality>
         <ns1:TaxFileNumber>213412324</ns1:TaxFileNumber>
         <ns1:NightWorker>true</ns1:NightWorker>
         <ns1:OtherNames xsi:nil="true"/>
         <ns1:PayrollNumber>1956</ns1:PayrollNumber>
         <ns1:ProbationEnd>2009-09-17T00:00:00</ns1:ProbationEnd>
         <ns1:ProbationDocumentsSent xsi:nil="true"/>
         <ns1:ProbationMonths>3</ns1:ProbationMonths>
         <ns1:RetirementDate xsi:nil="true"/>
         <ns1:RetirementAge>67</ns1:RetirementAge>
         <ns1:WouldRehire xsi:nil="true"/>
         <ns1:SafetyReviewDate>2009-10-20T00:00:00</ns1:SafetyReviewDate>
         <ns1:StartDate>2009-06-17T00:00:00</ns1:StartDate>
         <ns1:MaritalStatus xsi:nil="true"/>
         <ns1:PhoneExtention>345</ns1:PhoneExtention>
         <ns1:Title>mrs</ns1:Title>
         <ns1:VDUUser>true</ns1:VDUUser>
         <ns1:WorkPermit>true</ns1:WorkPermit>
         <ns1:WorkPermitExpiryDate>2017-10-18T00:00:00</ns1:WorkPermitExpiryDate>
         <ns1:Disabled>false</ns1:Disabled>
         <ns1:DisabilityType xsi:nil="true"/>
         <ns1:DisabilityNotes xsi:nil="true"/>
         <ns1:CriminalRecordsCheckDate xsi:nil="true"/>
         <ns1:CriminalRecordsCheckType xsi:nil="true"/>
         <ns1:CriminalRecordsCheckResults xsi:nil="true"/>
         <ns1:Age>65</ns1:Age>
         <ns1:CriminalRecordsCheckNotes><html/></ns1:CriminalRecordsCheckNotes>
         <ns1:EmployeeReasonForLeaving xsi:nil="true"/>
         <ns1:EmployeeMiddleName>Vuki</ns1:EmployeeMiddleName>
         <ns1:UserAccount xsi:nil="true"/>
         <ns1:EmployeeCode>1956</ns1:EmployeeCode>
         <ns1:Location>12</ns1:Location>
         <ns1:EmployeeCriminalRecordsCheckBy xsi:nil="true"/>
         <ns1:EmployeeFairWorkStatement>false</ns1:EmployeeFairWorkStatement>
         <ns1:EmployeeFairWorkStatementDateRead xsi:nil="true"/>
         <ns1:EmployeeFairWorkStatementHanded>false</ns1:EmployeeFairWorkStatementHanded>
         <ns1:EmployeeFairWorkStatementHandedDate xsi:nil="true"/>
         <ns1:EmployeeFairWorkStatementDoneBy xsi:nil="true"/>
         <ns1:EmployeeFairWorkStatementEmailTo xsi:nil="true"/>
         <ns1:EmployeeFairWorkStatementFaxTo xsi:nil="true"/>
         <ns1:EmployeeFairWorkStatementNotes xsi:nil="true"/>
         <ns1:EmployeeSelfServiceActive>false</ns1:EmployeeSelfServiceActive>
         <ns1:EmployeeTerminatedBy xsi:nil="true"/>
         <ns1:MethodOfTermination xsi:nil="true"/>
         <ns1:DoNotExportToPayroll xsi:nil="true"/>
         <ns1:EmployeeTimeInLieuBalance>0</ns1:EmployeeTimeInLieuBalance>
         <ns1:EmployeeAboriginalOrTorresStrait xsi:nil="true"/>
         <ns1:EmployeePayrollCompanyCode xsi:nil="true"/>
         <ns1:EmployeeABN xsi:nil="true"/>
         <ns1:EmployeeAustralianResident xsi:nil="true"/>
         <ns1:EmployeeMedicare xsi:nil="true"/>
         <ns1:EmployeeHELPHECS xsi:nil="true"/>
         <ns1:EmployeeSFSS xsi:nil="true"/>
         <ns1:EmployeeNumberOfChildren xsi:nil="true"/>
         <ns1:EmployeePayLocations xsi:nil="true"/>
         <ns1:EmployeePayPoint xsi:nil="true"/>
         <ns1:EmployeeContractHours xsi:nil="true"/>
         <ns1:EmployeeDefaultCostCentre xsi:nil="true"/>
         <ns1:EmployeeFamilyTaxBenefit xsi:nil="true"/>
         <ns1:EmployeeDailyTaxing xsi:nil="true"/>
         <ns1:EmployeeTerminationReason xsi:nil="true"/>
         <ns1:EmployeeMicropayAnnualLeaveClass xsi:nil="true"/>
         <ns1:EmployeeMicropayAnnualLeaveCostCentre xsi:nil="true"/>
         <ns1:EmployeeMicropaySickLeaveClass xsi:nil="true"/>
         <ns1:EmployeeMicropayLongServiceLeaveClass xsi:nil="true"/>
         <ns1:EmployeeMicropaySickLeaveCostCentre xsi:nil="true"/>
         <ns1:EmployeeMicropayLongServiceLeaveCostCentre xsi:nil="true"/>
         <ns1:EmployeeCreatedInPayroll xsi:nil="true"/>
         <ns1:EmployeeRosterLiveContractName xsi:nil="true"/>
         <ns1:EmployeeRosterLivePayLevel xsi:nil="true"/>
         <ns1:EmployeeRosterLiveLocationName xsi:nil="true"/>
         <ns1:EmployeeRosterLiveDepartmentName xsi:nil="true"/>
         <ns1:EmployeeRosterLiveMaxHoursPerPayPeriod xsi:nil="true"/>
         <ns1:EmployeeReportsTo xsi:nil="true"/>
         <ns1:EmployeeApplicantReference xsi:nil="true"/>
         <ns1:EmployeeDriversLicenceClass xsi:nil="true"/>
         <ns1:EmployeeDriversLicenceExpiryDate xsi:nil="true"/>
         <ns1:PhoneNumber xsi:nil="true"/>
         <ns1:EmployeeFax xsi:nil="true"/>
         <ns1:EmployeeNextPosition xsi:nil="true"/>
         <ns1:EmployeeNextEmployer xsi:nil="true"/>
         <ns1:DoNotImportLeaveBalances xsi:nil="true"/>
         <ns1:TaxExempt xsi:nil="true"/>
         <ns1:TaxOverride xsi:nil="true"/>
         <ns1:TaxOverridePercentage xsi:nil="true"/>
         <ns1:PayeeSignaturePresentOnTaxDeclaration xsi:nil="true"/>
         <ns1:TFNDeclarationSignedDate xsi:nil="true"/>
         <ns1:TaxFreeThreshold xsi:nil="true"/>
         <ns1:CreatedOn>2009-01-29T10:03:20</ns1:CreatedOn>
         <ns1:LastUpdatedOn>2013-06-12T10:37:24</ns1:LastUpdatedOn>
       </ns1:objects>
     </queryObjectResponse>
   </ns1:queryObjectResponse>
 </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Insert/Update Records

A call to upsertObject generic function can be made to update or insert one or more objects in the system that are exposed in the WSDL. The call is made by passing objects containing some data and the name of the object. The function returns true if the operation is successful.

Item Explanation
upsertObject(objects, objectName) Generic format of upsertObject function
objects Contains one or more apiObjects
objectName Name of the object where the data is to be stored (e.g. Employee).
return True if successful

Delete Records

A call to the deleteObject generic function can be made to delete one or more objects from the system that are exposed in the WSDL. The call is made by passing objects containing “Id” field and the name of the object. The function returns true if the operation is successful.

Item Explanation
deleteObject(objects, objectName)) deleteObject
objects Contains one or more apiObjects. Object can contain single field Id only to avoid passing the whole object back to the server.
objectName Name of the object from which data is being removed (e.g. Employee).
return True if successful

Request

<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:webservices.subscribe-hr.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 

 <SOAP-ENV:Body>
   <ns1:deleteObject>
     <objects>
       <ns1:objects xsi:type="ns1:Employee">
         <ns1:Id>92</ns1:Id>
       </ns1:objects>
       <ns1:objects xsi:type="ns1:Employee">
         <ns1:Id>93</ns1:Id>
       </ns1:objects>
     </objects>
     <objectName>Employee</objectName>
   </ns1:deleteObject>
 </SOAP-ENV:Body>

</SOAP-ENV:Envelope>


Response

<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:webservices.subscribe-hr.com"> 

 <SOAP-ENV:Body>
   <ns1:deleteObjectResponse>
     <deleteObjectResponse>true</deleteObjectResponse>
   </ns1:deleteObjectResponse>
 </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Code Samples

Below are codes examples for Authentication, Query, Insert, Update and Delete Records.

Authentication

$client = new SoapClient($WSDLLocation, array( 'cache_wsdl' => 0, 'allow_self_signed' => true, 'verify_peer' => false, 'trace' => true, 'exceptions' => true ));

$token = $client->authenticate('user@company.com', 'yourpassword');

Query Records

Get employee record where employee surname is ‘Funaki’.
$client = new SoapClient($WSDLLocation, array( 'cache_wsdl' => 0, 'allow_self_signed' => true, 'verify_peer' => false, 'trace' => true, 'exceptions' => true ));

$token = $client->authenticate('user@company.com', 'yourpassword');
$employee = $client->queryObject('Employee', 'Surname = Funaki');

Insert Records

Create two new employees in the system, JOHN SMITH and MARY BROWN.
$client = new SoapClient($WSDLLocation, array( 'cache_wsdl' => 0, 'allow_self_signed' => true, 'verify_peer' => false, 'trace' => true, 'exceptions' => true ));

$token = $client->authenticate('user@company.com', 'yourpassword');

$employee->FirstName = 'JOHN';
$employee->Surname = 'SMITH';
$employee->EmployeeMiddleName = ;
 $employee->Gender = 'male';
$employee->DateOfBirth = '1945-08-29T12:00:00';
$employee->DateOfBirthSpecified = 'true';
$employee->Appointed = '2011-11-29T12:00:00';

$employee2->FirstName = 'MARY';
$employee2->Surname = 'BROWN';
$employee2->EmployeeMiddleName = ;
 $employee2->Gender = 'female';
$employee2->DateOfBirth = '1955-04-19T12:00:00';
$employee2->DateOfBirthSpecified = 'true';
$employee2->Appointed = '2013-02-19T12:00:00';

$employeeEncoded = new SoapVar($employee, SOAP_ENC_OBJECT, 'Employee', 'urn:webservices.subscribe-hr.com');
$employeeEncoded2 = new SoapVar($employee2, SOAP_ENC_OBJECT, 'Employee', 'urn:webservices.subscribe-hr.com');
$client->upsertObject(new SoapVar(array($employeeEncoded, $employeeEncoded2), SOAP_ENC_ARRAY, 'apiObjects', 'urn:webservices.subscribe-hr.com'), 'Employee');

Update Records

Update the surname for employee with Id 71.
$client = new SoapClient($WSDLLocation, array( 'cache_wsdl' => 0, 'allow_self_signed' => true, 'verify_peer' => false, 'trace' => true, 'exceptions' => true ));

$token = $client->authenticate('user@company.com', 'yourpassword');
$employee->Id = 71;
$employee->Surname = 'Newsurname';
$domainAPI->upsertObject($employee, 'Employee');

Delete Records

Delete employees with ids 92 and 93.
$client = new SoapClient($WSDLLocation, array( 'cache_wsdl' => 0, 'allow_self_signed' => true, 'verify_peer' => false, 'trace' => true, 'exceptions' => true ));

$token = $client->authenticate('user@company.com', 'yourpassword');

$employee->Id = 92;
$employeeEncoded = new SoapVar($employee, SOAP_ENC_OBJECT, 'Employee', 'urn:webservices.subscribe-hr.com');
$employee2->Id = 93;
$employeeEncoded2 = new SoapVar($employee2, SOAP_ENC_OBJECT, 'Employee', 'urn:webservices.subscribe-hr.com');
$client->deleteObject(new SoapVar(array($employeeEncoded, $employeeEncoded2), SOAP_ENC_ARRAY, 'apiObjects', 'urn:webservices.subscribe-hr.com'), 'Employee');

New API

Subscribe-HR API or SAPI for short is the primary way to get data out of, and put data into, the platform. It's an HTTP-based RESTful API that you can use to query, create, update and delete entities within Subscribe-HR. All the supported operations are outlined on apiary at the following link http://docs.subscribehr.apiary.io

SHaRpi Integration Module

The Integration Module provides a front-end configurable interface for setting up integrations using the RESTful API. Additional documentation can be found here: http://subscribehr.readthedocs.io/en/latest/sharpi.html

It contains the following two sections:

Processes

The Processes page allows you to define your JSONpath configuration file. There are 2 available tabs for this:

  1. Configuration: This tab holds the configuration file to be edited. The configuration file process can be run from here.
    • Run Processes: This will run the process currently loaded, hoever please note, the record needs to be saved and validated before running the process. Running process before saving it will execute previous version of configuration file.
  2. Events: This tab holds the log of events that occur when running the process.
Fields
Field Name Description
Name The name that will be assigned to the saved process
Last Executed The last time the process was run
Last Successful Execution The last time process has completed successfully

Authentication

The Authentication records provide a record that can be referenced in your configuration Processes record. This authentication record holds the access tokens and keys depending on the authentication type.

The following fields are available:

  • Type: Determines the type of authentication. Options are: OAuth2.0 and Authorization Header.
  • Name: The name of the integration.
  • Grant Type: The Authorisation grant type.
  • Client ID: A field for the string that identifies the Client to be entered.
  • Client Secret: An encrypted field for holding a key belonging to the client.
  • Refresh Token: An encrypted field for holding the refresh token response after making a call.
  • Access Token Expiry: The date and time the Access toekn expires.
  • Refresh Token Expiry: The date and time the refresh token expires.
  • URL: The initial URL that the authorisation is sent to.
  • Scope: The scope of the access for the integration.
  • Access Token URL: The inital URL the access token is sent to.
  • Request Parameters: The parameters for SHaRpi to request new tokens.
  • Header Name: The name of the Authorization Header.
  • Authorisation Method: The method of Authorisation used by the header.

Subscribehr logo.gif

Retrieved from "https://wiki.subscribe-hr.com.au/index.php?title=Integration-Module&oldid=6324"