InTime provides a SOAP Web Service Interface that allows two-way flow of information to external systems. This enables automated and efficient transfer of data to and from your other systems reducing effort and duplication.
...
It is important to enclose your web service calls in try / catch blocks as Exceptions are used as the mechanism for feeding back any issues. For example if you attempt to create a placement without providing an External ID, an exception will be returned from the Web Service call with an appropriate message.
Client Code - Pseudocode examples
WEBSERVICE PSEUDOCODE FOR FRONTEND SYSTEM:
#Consultant |
|---|
RETRIEVING UPDATES FROM INTIME:
def entityList = getModifiedItemsWithRefCode(java.lang.String token, java.util.Calendar since) |
|---|
RETRIEVING INVOICE LINKS:
def entityList = getModifiedItemsWithRefCode(java.lang.String token, java.util.Calendar since) |
|---|
Java Code
Authenticate
try { //Create an instance of the stub IntimeServiceV2_9Stub stub = new IntimeServiceV2_9Stub("https://demo.in-time.co.uk/services/IntimeServiceV2_9?wsdl"); //Get an authentication token IntimeServiceV2_9Stub.Authenticate auth=new IntimeServiceV2_9Stub.Authenticate(); auth.setAgencyRefCode("<supplied_credentials>"); auth.setUsername("<supplied_credentials>"); auth.setPassword("<supplied_credentials>"); IntimeServiceV2_9Stub.AuthenticateResponse authResp=stub.authenticate(auth); String ticket=authResp.get_return(); System.out.println("Authentication token:" + ticket); //Use this authentication token (ticket) to pass in to any of the other WebService calls } catch (java.lang.Exception e) { System.out.println("Exception occurred: " + e); } |
|---|
...
try{ //Attempt to read the placement first to check if it already exists IntimeServiceV2_9Stub.GetPlacementByExternalId getPlacementRequest=new IntimeServiceV2_9Stub.GetPlacementByExternalId(); getPlacementRequest.setId("WEB-PLC-001"); getPlacementRequest.setToken(ticket); GetPlacementByExternalIdResponse placementResponse=stub.getPlacementByExternalId(getPlacementRequest); IntimeServiceV2_9Stub.Placement placement=placementResponse.get_return(); if (placement == null) { //placement does not exist placement = new IntimeServiceV2_9Stub.Placement(); placement.setExternalId("WEB-PLC-001"); } //Consultant IntimeServiceV2_9Stub.Consultant consultant= new IntimeServiceV2_9Stub.Consultant(); IntimeServiceV2_9Stub.GetConsultantsByExternalId getConsultantRequest=new IntimeServiceV2_9Stub.GetConsultantsByExternalId(); getConsultantRequest.setId("WEB-CON01"); getConsultantRequest.setToken(ticket); //from authenticate call GetConsultantsByExternalIdResponse consultantResponse=stub.getConsultantsByExternalId(getConsultantRequest); IntimeServiceV2_9Stub.Consultant[] cons=consultantResponse.get_return(); if (cons== null || cons.size() < 1) { //consultant did not exist consultant.setExternalId("WEB-CON01"); consultant.setFirstname("Web"); consultant.setLastname("Consultant"); consultant.setEmail("C@c.com"); IntimeServiceV2_9Stub.CreateOrUpdateConsultant createConsultantRequest = new IntimeServiceV2_9Stub.CreateOrUpdateConsultant(); createConsultantRequest.setToken(ticket); createConsultantRequest.setConsultant(consultant); IntimeServiceV2_9Stub.CreateOrUpdateConsultantResponse createConsultantResult=stub.createOrUpdateConsultant(createConsultantRequest); if (createConsultantResult != null) { System.out.println("Created/updated Consultant with ID:" + createConsultantResult.get_return()); } } else { consultant = cons[0]; } placement.setConsultant(consultant); //Client IntimeServiceV2_9Stub.Client client = new IntimeServiceV2_9Stub.Client(); IntimeServiceV2_9Stub.GetClientsByExternalId getClientRequest=new IntimeServiceV2_9Stub.GetClientsByExternalId(); getClientRequest.setId("WEB-CLI01"); getClientRequest.setToken(ticket); //from authenticate call GetClientsByExternalIdResponse clientResponse=stub.getClientsByExternalId(getClientRequest); IntimeServiceV2_9Stub.Client[] clients=clientResponse.get_return(); if (clients== null || clients.size() < 1) { //client did not exist client.setExternalId("WEB-CLI01"); client.setName("Web Client 001"); client.setTermsTemplateName("Default Charge Terms"); //populate other fields IntimeServiceV2_9Stub.CreateOrUpdateClient createClientRequest = new IntimeServiceV2_9Stub.CreateOrUpdateClient(); createClientRequest.setToken(ticket); createClientRequest.setClient(client); IntimeServiceV2_9Stub.CreateOrUpdateClientResponse createClientResult=stub.createOrUpdateClient(createClientRequest); if (createClientResult != null) { System.out.println("Created/updated Client with ID:" + createClientResult.get_return()); } } else { client = clients[0]; } placement.setClient(client); //Manager IntimeServiceV2_9Stub.Manager manager = new IntimeServiceV2_9Stub.Manager(); IntimeServiceV2_9Stub.GetManagersByExternalId getManagerRequest=new IntimeServiceV2_9Stub.GetManagersByExternalId(); //Worker IntimeServiceV2_9Stub.GetWorkersByExternalId getWorkerRequest=new IntimeServiceV2_9Stub.GetWorkersByExternalId();
//set/update other placement fields placement.setContractedHours(new BigDecimal(37.5)); placement.setCurrencyForCharge("GBP"); placement.setCurrencyForPayExpenses("GBP"); placement.setCurrencyForPayTimesheets("GBP"); placement.setChargeableExpenseApprovalRoute("Client Manager Approval"); placement.setNonChargeableExpenseApprovalRoute("Auto Approval"); placement.setTimesheetApprovalRoute("Auto Approval"); placement.setExpenseTemplate("Default"); placement.setHolidayAccuralRate(0.12); placement.setJobDescription("Web Placement 1"); placement.setJobTitle("Web Test 001"); placement.setNoCommunications(""); placement.setPurchaseOrderNum("po_num"); placement.setSalesCostCentre("scc"); placement.setTimesheetDateCalculatorName("weekly"); placement.setPerm(false); Calendar cal1 = Calendar.getInstance(java.util.TimeZone.getTimeZone("GMT")); cal1.set(2021, 3, 1, 0, 0, 0); placement.setStart(cal1); Calendar cal2 = Calendar.getInstance(java.util.TimeZone.getTimeZone("GMT")); cal2.set(2023, 3, 1, 0, 0, 0); placement.setEnd(cal2); IntimeServiceV2_9Stub.Rate[] rates = new IntimeServiceV2_9Stub.Rate[1]; IntimeServiceV2_9Stub.Rate rate1 = new IntimeServiceV2_9Stub.Rate(); rate1.setName("Standard Hours"); rate1.setPay(new BigDecimal(9.99)); rate1.setCharge(new BigDecimal(11.11)); rate1.setPayElementCode("001"); rate1.setPeriod("Hourly"); rate1.setPeriodDuration(60); rate1.setPriorityOrder(0); rate1.setTimePattern("DEFAULT"); rate1.setTimesheetFields("START_FINISH_BREAK"); rate1.setSelectableByWorkers(true); rates[0] = rate1; placement.setRates(rates); IntimeServiceV2_9Stub.CreateOrUpdatePlacement request = new IntimeServiceV2_9Stub.CreateOrUpdatePlacement(); request.setToken(ticket); request.setPlacement(placement); IntimeServiceV2_9Stub.CreateOrUpdatePlacementResponse result=stub.createOrUpdatePlacement(request); if (result != null) { System.out.println("Created/updated Placement with ID:" + result.get_return()); } } catch (java.lang.Exception e) { System.out.println("Exception occurred: " + e); } |
|---|
Update a Placement
try{ //Attempt to read the placement first IntimeServiceV2_9Stub.GetPlacementByExternalId getPlacementRequest=new IntimeServiceV2_9Stub.GetPlacementByExternalId(); getPlacementRequest.setId("WEB-PLC-001"); getPlacementRequest.setToken(ticket); GetPlacementByExternalIdResponse placementResponse=stub.getPlacementByExternalId(getPlacementRequest); IntimeServiceV2_9Stub.Placement placement=placementResponse.get_return(); if (placement == null) { //placement does not exist placement = new IntimeServiceV2_9Stub.Placement(); //refer to create placement process } //Apply any Consultant changes IntimeServiceV2_9Stub.Consultant consultant=placement.getConsultant(); consultant.setDepartment("Web testing"); //Apply any Client changes IntimeServiceV2_9Stub.Client client=placement.getClient(); client.getInvoicingContact().getAddress().setLine1("123 Test Street"); //Apply any Manager changes IntimeServiceV2_9Stub.Manager manager=placement.getManager(); //Apply any Worker changes IntimeServiceV2_9Stub.Worker worker=placement.getWorker(); worker.getLimitedCompany().setCompanyVatNo("67896789"); worker.setDefaultPaymentCurrency("GBP"); //set/update other placement fields placement.setPurchaseOrderNum("po_num 2"); placement.setSalesCostCentre("scc mod"); for (IntimeServiceV2_9Stub.Rate rate : placement.getRates()) { if(rate.getName() == "Standard Hours") { //update pay/charge rate rate1.setPay(new BigDecimal(15)); rate1.setCharge(new BigDecimal(22.50)); } } IntimeServiceV2_9Stub.CreateOrUpdatePlacement request = new IntimeServiceV2_9Stub.CreateOrUpdatePlacement(); request.setToken(ticket); request.setPlacement(placement); IntimeServiceV2_9Stub.CreateOrUpdatePlacementResponse result=stub.createOrUpdatePlacement(request); if (result != null) { System.out.println("Created/updated Placement with ID:" + result.get_return()); } } catch (java.lang.Exception e) { System.out.println("Exception occurred: " + e); } |
|---|
Create or update a Timesheet
...
| Field | Constant | Comment | Notes |
|---|---|---|---|
| Client | |||
| invoicePeriod | 0 | Weekly | |
| 1 | Two-Weekly | ||
| 2 | Four-Weekly | ||
| 3 | Calendar Monthly | ||
| 4 | 4-4-5 | ||
| howSendInvoices | 0 | Post | Invoice delivery method |
| 1 | |||
| 2 | Fax | ||
| 3 | Not sent | ||
| Worker | |||
| workerType | paye | For PAYE Workers | |
| ltd | For Ltd Company Workers | ||
| external-contractor | For Non Ltd Company Workers | ||
| cis | For CIS Workers | ||
| umb | For Workers operating through an Umbrella | You must also reference the umbrella against the worker, otherwise the worker will appear as LTD. | |
| ir35 | For workers inside scope of IR35 (deemed) | ||
| cisBusinessType | SoleTrader | ||
| Company | |||
| Trust | |||
| Partnership | |||
| cisPercentage | 0 | ||
| 20 | |||
| 30 | |||
| paymentFrequency | weekly | ||
| monthly | |||
| <InPay Payroll Name> | If InPay connected, for PAYE workers, use the InPay Payroll Name | ||
| timesheetsOnInvoices | 0 | Timesheets On Invoices | |
| 1 | Timesheets Not On Invoices | ||
| paperOnInvoices | -1 | Agency Default | |
| 0 | No Attachments | ||
| 1 | Attach Paper Timesheets | ||
| 2 | Attach Expense Group Paper | ||
| 4 | Attach Expense Receipts Paper | ||
| <sum of the above> | Attach the appropriate paper | For example, 5 to attach timesheets and receipts | |
| gender | M | ||
| F | |||
| LTD invoice period | 0 | Weekly | |
| 1 | Two-Weekly | ||
| 2 | Four-Weekly | ||
| 3 | Calendar Monthly | ||
| 4 | 4-4-5 | ||
| Payment Method | bacs | NOT CASE SENSITIVE | |
| cheque | NOT CASE SENSITIVE | ||
| cash | NOT CASE SENSITIVE | ||
| chaps | NOT CASE SENSITIVE | ||
| ach | NOT CASE SENSITIVE | ||
| international | NOT CASE SENSITIVE | ||
| building society | NOT CASE SENSITIVE | ||
| Placement | |||
| layout | standard | See Maintaining Placements | |
| calendar | |||
| timesheetDateCalculator | weekly | See Maintaining Placements. You can see all possible values for this in the ui. | |
| monthly | |||
| <many more> | See UI for all options. | ||
| Rates | |||
| period | 60 | For hourly rates entered in hours format (hours only or start, break, finish). | |
| 1440 | For fixed rates of a specified duration entered in decimal format (decimal or tickbox) | ||
| periodDuration | <any integer> | The duration in minutes for the fixed rate (e.g. 60 for hours, 480 for a day). | |
| timePattern | default | Will use the selected default time pattern | |
| <any string> | The string should match the name of a time pattern in the system | ||
| timesheetFields | START_FINISH_BREAK | Enter start, break, finish | Only when period above is 60 |
| HOURS | Enter hours only | Only when period above is 60 | |
| DECIMAL | Enter time as a decimal | Only when period above is 1440 | |
| DAY | Tickbox only (equivalent to entering decimals as 1.00) | Only when period above is 1440 | |
InvoiceAdjustmentSettings (Company / Worker) | |||
| AdjustBy | 0 | Fixed Amount | |
| 1 | Percentage | ||
| AdjustPer | 0 | Per Worker | |
| 1 | Per Timesheet | ||
| 2 | Per Invoice | ||
| AdjustType | 0 | Addition | |
| 1 | Deduction | ||
ExpenseType EntryMethod | 0 | Gross value | Populate the GrossValue and optionally the VatAmount field on an ExpenseItem with this entry method |
| 1 | Net Value | Populate the NetValue field on an ExpenseItem with this entry method | |
| 2 | Units and Unit net | Populate the Unit and UnitNet fields on an ExpenseItem with this entry method. E.g. Set Unit = 30 and UnitNet = 0.45 to claim 30 miles at 45p per mile. | |
| 3 | Units and Net | Populate the Unit and Net Value fields on an ExpenseItem with this entry method. |