Introduction to the Subscribe-HR RESTful API

From Subscribe-HR Wiki Help
Jump to: navigation, search
(Authentication)
(Authentication)
(15 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{page.name: Integration Module: Introduction to the Subscribe-HR API - Subscribe-HR Wiki}}
+
{{page.name: Integration Module: Introduction to the Subscribe-HR RESTful API - Subscribe-HR Wiki}}
{{page.head: Introduction to the Subscribe-HR API}}
+
{{page.head: Introduction to the Subscribe-HR RESTful API}}
  
 
__TOC__
 
__TOC__
  
==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==
+
=RESTful API=
  
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.
+
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
  
==WSDL File Download==
+
==SHaRpi Integration Module==
  
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.
+
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
# Login to your Subscribe-HR account.
+
# 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===
+
It contains the following two sections:
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.
+
# Navigating to Development > Objects > Select an Object.
+
# Select <b>Include In WSDL</b> flag to Yes
+
# Select the <b>Save</b> button.
+
After accessing WSDL URL again you will notice that the object is now part of the definition.
+
  
==Error Handling==
+
==Processes==
  
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.
+
The Processes page allows you to define your JSONpath configuration file. There are 2 available tabs for this:
 
+
# Configuration: This tab holds the configuration file to be edited. The configuration file process can be run from here.
<?xml version="1.0" encoding="UTF-8"?>
+
#*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.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
+
# Events: This tab holds the log of events that occur when running the process.
  <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.
+
  
 +
==Fields==
 
<table border="1" width="700" id="table1" cellspacing="1">
 
<table border="1" width="700" id="table1" cellspacing="1">
 
<tr>
 
<tr>
<td width="150"><font face="Arial" size="2">Item</font></td>
+
<td width="150"><b><font face="Arial" size="2">Field Name</font></b></td>
<td width="550"><font face="Arial" size="2">Explanation</font></td>
+
<td width="550"><b><font face="Arial" size="2">Description</font></b></td>
 
</tr>
 
</tr>
<tr>
+
        <tr>
<td width="150"><font face="Arial" size="2">authenticate(username, password)</font></td>
+
<td width="150"><font face="Arial" size="2">UUID</font></td>
<td width="550"><font face="Arial" size="2">Generic format of authenticate method</font></td>
+
<td width="550"><font face="Arial" size="2">Unique record ID</font></td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td width="150"><font face="Arial" size="2">username</font></td>
+
<td width="150"><font face="Arial" size="2">Name</font></td>
<td width="550"><font face="Arial" size="2">Subscribe-HR username</font></td>
+
<td width="550"><font face="Arial" size="2">The name that will be assigned to the saved process</font></td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td width="150"><font face="Arial" size="2">password</font></td>
+
<td width="150"><font face="Arial" size="2">Last Executed</font></td>
<td width="550"><font face="Arial" size="2">Subscribe-HR password</font></td>
+
<td width="550"><font face="Arial" size="2"> The last time the process was run</font></td>
</tr>
+
        </tr>
 
<tr>
 
<tr>
<td width="150"><font face="Arial" size="2">return</font></td>
+
<td width="150"><font face="Arial" size="2">Last Successful Execution</font></td>
<td width="550"><font face="Arial" size="2">Session token</font></td>
+
<td width="550"><font face="Arial" size="2"> The last time process has completed successfully</font></td>
</tr>
+
</tr>
</table>
+
<tr>
 +
<td width="150"><font face="Arial" size="2">Enable Scheduler</font></td>
 +
<td width="550"><font face="Arial" size="2">Enable scheduler to run the process on predefined interval</font></td>
 +
</tr>
 +
<tr>
 +
<td width="150"><font face="Arial" size="2">Interval</font></td>
 +
<td width="550"><font face="Arial" size="2">Scheduler interval - must be a whole number e.g. 10 minutes</font></td>
 +
</tr>
 +
<tr>
 +
<td width="150"><font face="Arial" size="2">Units</font></td>
 +
<td width="550"><font face="Arial" size="2"> Interval units e.g. minutes, hours, days etc.</font></td>
 +
</tr>
 +
<tr>
 +
<td width="150"><font face="Arial" size="2">Start Date</font></td>
 +
<td width="550"><font face="Arial" size="2">Date when scheduler will become active.</font></td>
 +
</tr>
 +
<tr>
 +
<td width="150"><font face="Arial" size="2">Belongs to App</font></td>
 +
<td width="550"><font face="Arial" size="2">Select app if this authentication record is to be added to one of your apps.</font></td>
 +
</tr>
  
 
===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.
 
 
<table border="1" width="700" id="table1" cellspacing="1">
 
<tr>
 
<td width="150"><font face="Arial" size="2">Item</font></td>
 
<td width="550"><font face="Arial" size="2">Explanation</font></td>
 
</tr>
 
<tr>
 
<td width="250"><font face="Arial" size="2">queryObject(object, condition)</font></td>
 
<td width="450"><font face="Arial" size="2">Generic format of query function</font></td>
 
</tr>
 
<tr>
 
<td width="150"><font face="Arial" size="2">object</font></td>
 
<td width="550"><font face="Arial" size="2">Name of the system object (e.g. Employee or EmployeeAbsenceDetails).</font></td>
 
</tr>
 
<tr>
 
<td width="150"><font face="Arial" size="2">condition</font></td>
 
<td width="550"><font face="Arial" size="2">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</font></td>
 
</tr>
 
<tr>
 
<td width="150"><font face="Arial" size="2">return</font></td>
 
<td width="550"><font face="Arial" size="2">queryResponseObject.</font></td>
 
</tr>
 
 
</table>
 
</table>
  
==Conditional Operators Matrix==
+
==Authentication==
The table below shows the conditional operator, the name of the condition and an example of the use of the condition in a query.
+
 
+
<table border="1" width="700" id="table1" cellspacing="1">
+
<tr>
+
<td width="100"><b><font face="Arial" size="2"></font>Condition</b></td>
+
<td width="150"><b><font face="Arial" size="2"></font>Name</b></td>
+
<td width="450"><b><font face="Arial" size="2"></font>Example</b></td>
+
</tr>
+
<tr>
+
<td width="100"><b><font face="Arial" size="2"></font>>=</b></td>
+
<td width="150"><b><font face="Arial" size="2"></font>Greater or Equal To</b></td>
+
<td width="450"><b><font face="Arial" size="2"></font>queryObject(“Employee”, “StartDate>=2009-06-17”)</b></td>
+
</tr>
+
<tr>
+
<td width="100"><b><font face="Arial" size="2"></font><=</b></td>
+
<td width="150"><b><font face="Arial" size="2"></font>Less or Equal To</b></td>
+
<td width="450"><b><font face="Arial" size="2"></font>queryObject(“Employee”, “StartDate<=2009-06-17”)</b></td>
+
</tr>
+
<tr>
+
<td width="100"><b><font face="Arial" size="2"></font>>=</b></td>
+
<td width="150"><b><font face="Arial" size="2"></font>Greater or Equal To</b></td>
+
<td width="450"><b><font face="Arial" size="2"></font>queryObject(“Employee”, “StartDate>=2009-06-17”)</b></td>
+
</tr>
+
<tr>
+
<td width="100"><b><font face="Arial" size="2"></font><></b></td>
+
<td width="150"><b><font face="Arial" size="2"></font>Not Equal To</b></td>
+
<td width="450"><b><font face="Arial" size="2"></font>queryObject(“Employee”, “Id<>71”)</b></td>
+
</tr>
+
<tr>
+
<td width="100"><b><font face="Arial" size="2"></font>=</b></td>
+
<td width="150"><b><font face="Arial" size="2"></font>Equal To</b></td>
+
<td width="450"><b><font face="Arial" size="2"></font>queryObject(“Employee”, “Id=71”)</b></td>
+
</tr>
+
<tr>
+
<td width="100"><b><font face="Arial" size="2"></font>></b></td>
+
<td width="150"><b><font face="Arial" size="2"></font>Greater Than</b></td>
+
<td width="450"><b><font face="Arial" size="2"></font>queryObject(“Employee”, “Id>71”)</b></td>
+
</tr>
+
<tr>
+
<td width="100"><b><font face="Arial" size="2"></font><></b></td>
+
<td width="150"><b><font face="Arial" size="2"></font>Equal To</b></td>
+
<td width="450"><b><font face="Arial" size="2"></font>queryObject(“Employee”, “Id=71”)</b></td>
+
</tr>
+
<tr>
+
<td width="100"><b><font face="Arial" size="2"></font><</b></td>
+
<td width="150"><b><font face="Arial" size="2"></font>Less Than</b></td>
+
<td width="450"><b><font face="Arial" size="2"></font>queryObject(“Employee”, “Id<100”)</b></td>
+
</tr>
+
<tr>
+
<td width="100"><b><font face="Arial" size="2"></font>IN</b></td>
+
<td width="150"><b><font face="Arial" size="2"></font>In a List</b></td>
+
<td width="450"><b><font face="Arial" size="2"></font>queryObject(“Employee”, “Id IN (71, 72, 73)”)</b></td>
+
</tr>
+
<tr>
+
<td width="100"><b><font face="Arial" size="2"></font>AND</b></td>
+
<td width="150"><b><font face="Arial" size="2"></font>And Condition</b></td>
+
<td width="450"><b><font face="Arial" size="2"></font>queryObject(“Employee”, “Id IN (71, 72, 73) AND StartDate>=2009-06-17”)</b></td>
+
</tr>
+
</table>
+
 
+
===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>&lt;html/&gt;</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>&lt;html/&gt;</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.
+
 
+
<table border="1" width="700" id="table1" cellspacing="1">
+
<tr>
+
<td width="150"><font face="Arial" size="2">Item</font></td>
+
<td width="550"><font face="Arial" size="2">Explanation</font></td>
+
</tr>
+
<tr>
+
<td width="150"><font face="Arial" size="2">upsertObject(objects, objectName)</font></td>
+
<td width="550"><font face="Arial" size="2">Generic format of upsertObject function</font></td>
+
</tr>
+
<tr>
+
<td width="150"><font face="Arial" size="2">objects</font></td>
+
<td width="550"><font face="Arial" size="2">Contains one or more apiObjects</font></td>
+
</tr>
+
<tr>
+
<td width="150"><font face="Arial" size="2">objectName</font></td>
+
<td width="550"><font face="Arial" size="2">Name of the object where the data is to be stored (e.g. Employee).</font></td>
+
</tr>
+
<tr>
+
<td width="150"><font face="Arial" size="2">return</font></td>
+
<td width="550"><font face="Arial" size="2">True if successful</font></td>
+
</tr>
+
</table>
+
 
+
==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.
+
 
+
<table border="1" width="700" id="table1" cellspacing="1">
+
<tr>
+
<td width="150"><font face="Arial" size="2">Item</font></td>
+
<td width="550"><font face="Arial" size="2">Explanation</font></td>
+
</tr>
+
<tr>
+
<td width="150"><font face="Arial" size="2">deleteObject(objects, objectName))</font></td>
+
<td width="550"><font face="Arial" size="2">deleteObject</font></td>
+
</tr>
+
<tr>
+
<td width="150"><font face="Arial" size="2">objects</font></td>
+
<td width="550"><font face="Arial" size="2">Contains one or more apiObjects. Object can contain single field Id only to avoid passing the whole object back to the server.</font></td>
+
</tr>
+
<tr>
+
<td width="150"><font face="Arial" size="2">objectName</font></td>
+
<td width="550"><font face="Arial" size="2">Name of the object from which data is being removed (e.g. Employee).</font></td>
+
</tr>
+
<tr>
+
<td width="150"><font face="Arial" size="2">return</font></td>
+
<td width="550"><font face="Arial" size="2">True if successful</font></td>
+
</tr>
+
</table>
+
 
+
===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’.<br>
+
$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');<br>
+
$employee = $client->queryObject('Employee', 'Surname = Funaki');
+
 
+
===Insert Records===
+
Create two new employees in the system, JOHN SMITH and MARY BROWN.<br>
+
$client = new SoapClient($WSDLLocation, array(
+
'cache_wsdl' => 0,
+
'allow_self_signed' => true,
+
'verify_peer' => false,
+
'trace' => true,
+
'exceptions' => true
+
));<br>
+
+
$token = $client->authenticate('user@company.com', 'yourpassword');<br>
+
 
+
$employee->FirstName = 'JOHN';<br>
+
$employee->Surname = 'SMITH';<br>
+
$employee->EmployeeMiddleName = '';<br>
+
$employee->Gender = 'male';<br>
+
$employee->DateOfBirth = '1945-08-29T12:00:00';<br>
+
$employee->DateOfBirthSpecified = 'true';<br>
+
$employee->Appointed  = '2011-11-29T12:00:00';<br>
+
 
+
$employee2->FirstName = 'MARY';<br>
+
$employee2->Surname = 'BROWN';<br>
+
$employee2->EmployeeMiddleName = '';<br>
+
$employee2->Gender = 'female';<br>
+
$employee2->DateOfBirth = '1955-04-19T12:00:00';<br>
+
$employee2->DateOfBirthSpecified = 'true';<br>
+
$employee2->Appointed  = '2013-02-19T12:00:00';<br>
+
 
+
$employeeEncoded = new SoapVar($employee, SOAP_ENC_OBJECT, 'Employee', 'urn:webservices.subscribe-hr.com');<br>
+
$employeeEncoded2 = new SoapVar($employee2, SOAP_ENC_OBJECT, 'Employee', 'urn:webservices.subscribe-hr.com');<br>
+
$client->upsertObject(new SoapVar(array($employeeEncoded, $employeeEncoded2), SOAP_ENC_ARRAY, 'apiObjects', 'urn:webservices.subscribe-hr.com'), 'Employee');<br>
+
 
+
===Update Records===
+
Update the surname for employee with Id 71.<br>
+
$client = new SoapClient($WSDLLocation, array(
+
'cache_wsdl' => 0,
+
'allow_self_signed' => true,
+
'verify_peer' => false,
+
'trace' => true,
+
'exceptions' => true
+
));<br>
+
+
$token = $client->authenticate('user@company.com', 'yourpassword');<br>
+
$employee->Id = 71;<br>
+
$employee->Surname = 'Newsurname';<br>
+
$domainAPI->upsertObject($employee, 'Employee');<br>
+
 
+
===Delete Records===
+
Delete employees with ids 92 and 93.<br>
+
$client = new SoapClient($WSDLLocation, array(
+
'cache_wsdl' => 0,
+
'allow_self_signed' => true,
+
'verify_peer' => false,
+
'trace' => true,
+
'exceptions' => true
+
));<br>
+
+
$token = $client->authenticate('user@company.com', 'yourpassword');<br>
+
 
+
$employee->Id = 92;<br>
+
$employeeEncoded = new SoapVar($employee, SOAP_ENC_OBJECT, 'Employee', 'urn:webservices.subscribe-hr.com');<br>
+
$employee2->Id = 93;<br>
+
$employeeEncoded2 = new SoapVar($employee2, SOAP_ENC_OBJECT, 'Employee', 'urn:webservices.subscribe-hr.com');<br>
+
$client->deleteObject(new SoapVar(array($employeeEncoded, $employeeEncoded2), SOAP_ENC_ARRAY, 'apiObjects', 'urn:webservices.subscribe-hr.com'), 'Employee');<br>
+
 
+
==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:
+
# Configuration: This tab holds the configuration file to be edited. The configuration file process can be run from here.
+
# Events: This tab holds the log of events that occur when running the process.
+
 
+
===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 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:
 
The following fields are available:
 +
* '''UUID''': Unique record ID.
 
* '''Type''': Determines the type of authentication. Options are: '''OAuth2.0''' and '''Authorization Header'''.
 
* '''Type''': Determines the type of authentication. Options are: '''OAuth2.0''' and '''Authorization Header'''.
 
* '''Name''': The name of the integration.
 
* '''Name''': The name of the integration.
Line 542: Line 87:
 
* '''Request Parameters''': The parameters for SHaRpi to request new tokens.
 
* '''Request Parameters''': The parameters for SHaRpi to request new tokens.
 
* '''Header Name''': The name of the Authorization Header.
 
* '''Header Name''': The name of the Authorization Header.
* '''Authorisation Method''': The method of Authroisation used by the header.
+
* '''Authorisation Method''': The method of Authorisation used by the header.
 +
* '''Belongs to App''': Select app if this authentication record is to be added to one of your apps.
  
 
[[File:subscribehr_logo.gif]]
 
[[File:subscribehr_logo.gif]]

Revision as of 01:00, 1 April 2019


RESTful 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
UUID Unique record ID
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
Enable Scheduler Enable scheduler to run the process on predefined interval
Interval Scheduler interval - must be a whole number e.g. 10 minutes
Units Interval units e.g. minutes, hours, days etc.
Start Date Date when scheduler will become active.
Belongs to App Select app if this authentication record is to be added to one of your apps.

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:

  • UUID: Unique record ID.
  • 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.
  • Belongs to App: Select app if this authentication record is to be added to one of your apps.

Subscribehr logo.gif