Versions Compared

Version Old Version 10 New Version 11
Changes made by

Mark Holland (Unlicensed)

Mark Holland (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The full technical API specification is available here.

Scenarios and uses

This section describes various scenarios of how the Web Services can be used.

Authentication

Before you can call any other InTime Web Service method you must first call the authenticate() method. Providing valid credentials to this method will return an authentication token that must be provided with all other Web Service calls.

Modified Items

getModifiedItems() and getModifiedItemsWithRefCode and getModifiedItemsWithRefCode() functions return a list of items that have been updated since a specific date and time. This is useful where you wish to maintain a copy of various entities in an external system.

...

Once you have a current copy you can then periodically check for any items that have been modified since the last update and just update the details of those modified items. This is much more efficient than attempting to update all entities every the time. 

Data Retrieval (Read operations)

There are a number of methods that enable you to read back the full details of an entity. The required entity can be identified by a number of different fields. Examples are:

getWorkerByRefCode() returns the worker entity that has the specified RefCode.

getClientById() returns the Client entity with the specified Id.

getPlacementByExternalId() returns the Placement entity with the specified External Id.

getUsersByExternalId() returns a list of User entities that have the specified External Id. For this method a list of items rather than a single items is returned as is it possible, although not advisable, to have multiple users with the same external Id.

getTimesheetById() returns the Timesheet with the specified Id.

...

There are also a number of Search type methods that retrieve multiple results. This enables you to retrieve a set of entities that are filtered according to some criteria. Examples are:

getTimesheetIdsWithStatusAndDatesForWorker() This returns a list of Timesheet Ids for a specific Worker that have a specific status within a certain date range.

getInvoicesForClient() This returns a list of all invoices relating to a specific Client.  

Data Creation (Write Operations)

With version 2.0 it is now possible to create data in InTime via the Web Services. This includes the following entities: Worker, Client, Manager, Consultant, Provider, Placement and Timesheet. These mostly take the form of createOrUpdateXXX as this allows the same method to be used to create the entity if it doesn't exist or update it if it does. Examples are: createOrUpdateWorker(), createorUpdatePlacement() and createOrUpdateProvider()

Timesheets

updateTimesheet() method  method will create a new Timesheet or update an existing one if it exists in Draft status. The Timesheet will be saved with Draft status. The Timesheet object you supply to this method must contain all the necessary data which includes a valid Placement reference, the Period End date and one or more Shifts. Each Shift must reference a valid Rate from the Placement, the Time worker or a Decimal value and the Date on which it was worked. It will normally be necessary to retrieve the details of the Placement the Timesheet relates to in order to correctly complete all the required fields.

submitTimesheet() would then be called to submit the Timesheet for approval once it has all the necessary time (Shifts) added to it. 

rejectTimesheet() or approveTimesheet() are then used to process the approval.

revertTimesheet() can also be used to revert a Submitted or Approved status Timesheet if required. This has exactly the same result as reverting a Timesheet though the InTime UI.

Single Sign On

getSingleSignOnToken() can be used to log in to InTime using an existing InTime User account. This method returns a token that you can then append to any valid InTime URL and it will allow you to retrieve the page as if you were logged into the system directly. This means you can embed InTime pages within another web site or retrieve other data.

Other methods

The interface also provides various other methods. Some examples:

getMissingTimesheetsForPlacement() identifes identifies any periods within the specified range that do not contain an approved timesheet. The reponse response will include a status that indicates if it is Missing, Draft or Submitted.

getAllPayElements() returns a list of all Pay Elements present in the system.

getURLForContractorsPayslip() retrieves the URL to viewing a workers Payslips. *InPay Linked systems only

Getting started

The InTime Web Service uses the Simple Object Access Protocol (SOAP) interface as opposed to REST. This is a stricter protocol than REST which means you can only call the defined methods available and the return types will be in a fixed format. Normally you would start by building "stub" code against the WSDL file that defines the interface.

...

Include and reference these files in your application and you will be able to make calls to the Web Services. Some examples are given below.

Java Code Examples

Authenticate

try {

//Create an instance of the stub

IntimeServiceV2_0Stub stub = new IntimeServiceV2_0Stub("https://demo.in-time.co.uk/services/IntimeServiceV2_0?wsdl");


//Get an authentication token

IntimeServiceV2_0Stub.Authenticate auth=new IntimeServiceV2_0Stub.Authenticate();

auth.setAgencyRefCode("<supplied_credentials>");

auth.setUsername("<supplied_credentials>");

auth.setPassword("<supplied_credentials>");

IntimeServiceV2_0Stub.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);

}


Create or update a Worker

try {

IntimeServiceV2_0Stub.Worker worker = new IntimeServiceV2_0Stub.Worker();

worker.setExternalId("WKR_LTD_001");

worker.setFirstname("Ltd");

worker.setLastname("Worker");

worker.setEmail("x@x.com");

worker.setTitle("Mrs");

worker.setWorkerType("ltd");

worker.setGender("F");

worker.setSelfBilling(false);

worker.setAccountsReference("ACC_REF");

worker.setPaymentFrequency("Monthly");


String[] wConsolidation = new String[] { "destination","source","pay-currency","purchase-tax-code","worker","placement" };

worker.setConsolidation(wConsolidation);

String[] wCrouping = new String[] { "sheet","sheet-rate" };

worker.setGrouping(wCrouping);


Calendar cal = Calendar.getInstance(java.util.TimeZone.getTimeZone("GMT"));

cal.set(1980, 0, 1, 0, 0, 0);

cal.set(Calendar.MILLISECOND, 0);

worker.setDateOfBirth(cal);

Calendar cal2 = Calendar.getInstance(java.util.TimeZone.getTimeZone("GMT"));

cal2.set(2017, 0, 1, 0, 0, 0);

cal2.set(Calendar.MILLISECOND, 0);

worker.setDateOfJoining(cal2);


IntimeServiceV2_0Stub.Address address = new IntimeServiceV2_0Stub.Address();

address.setLine1("Address1");

address.setLine2("Add2");

address.setTown("Town");

address.setCounty("County");

address.setCountry("UK");

address.setPostcode("AB1 2CD");

address.setCountryCode("GB");

worker.setAddress(address);


BankAccount bank = new BankAccount();

bank.setAccountName("Ltd Wkr");

bank.setAccountNumber("12345678");

bank.setBank("bank");

bank.setSortCode("11-22-33");

worker.setBankAccount(bank);


Company ltdCompany = new Company();

ltdCompany.setName("Ltd Co Name");

ltdCompany.setCompanyNo("123456789");

ltdCompany.setCompanyVatNo("1234567890");

ltdCompany.setVatCode("T0");

worker.setLimitedCompany(ltdCompany);


IntimeServiceV2_0Stub.CreateOrUpdateWorker request = new IntimeServiceV2_0Stub.CreateOrUpdateWorker();

request.setToken(ticket);

request.setWorker(worker);


IntimeServiceV2_0Stub.CreateOrUpdateWorkerResponse result=stub.createOrUpdateWorker(request);

if (result != null) {

System.out.println("Created/updated Worker with ID:" + result.get_return());

}

} catch (java.lang.Exception e) {

System.out.println("Exception occurred: " + e);

} 

...



Create or update a Placement

try{

IntimeServiceV2_0Stub.Placement placement = new IntimeServiceV2_0Stub.Placement();


//referencing existing participants by External Id

IntimeServiceV2_0Stub.Worker worker = new IntimeServiceV2_0Stub.Worker();

worker.setExternalId("WKR_001");

placement.setWorker(worker);


IntimeServiceV2_0Stub.Consultant consultant = new IntimeServiceV2_0Stub.Consultant();

consultant.setExternalId("CONS_001");

placement.setConsultant(consultant);


IntimeServiceV2_0Stub.Client client = new IntimeServiceV2_0Stub.Client();

client.setExternalId("CLIENT_001");

placement.setClient(client);


IntimeServiceV2_0Stub.Manager manager = new IntimeServiceV2_0Stub.Manager();

manager.setExternalId("MGR_001");

placement.setManager(manager);


placement.setExternalId("WEB-PLC-001");

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(2017, 3, 1, 0, 0, 0);

placement.setStart(cal1);

Calendar cal2 = Calendar.getInstance(java.util.TimeZone.getTimeZone("GMT"));

cal2.set(2019, 3, 1, 0, 0, 0);

placement.setEnd(cal2);


IntimeServiceV2_0Stub.Rate[] rates = new IntimeServiceV2_0Stub.Rate[1];

IntimeServiceV2_0Stub.Rate rate1 = new IntimeServiceV2_0Stub.Rate();

rate1.setName("Standard Day");

rate1.setPay(new BigDecimal(99.99));

rate1.setCharge(new BigDecimal(111.11));

rate1.setPayElementCode("001");

rate1.setPeriod("fixed");

rate1.setPeriodDuration(480);

rate1.setPriorityOrder(0);

rate1.setTimePattern("DEFAULT");

rate1.setTimesheetFields("DECIMAL");

rate1.setSelectableByWorkers(true);

rates[0] = rate1;

placement.setRates(rates);


IntimeServiceV2_0Stub.CreateOrUpdatePlacement request = new IntimeServiceV2_0Stub.CreateOrUpdatePlacement();

request.setToken(ticket);

request.setPlacement(placement);


IntimeServiceV2_0Stub.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);

}



- getPlacement



- update timesheet

...