external_id.
When to use it
Use this destination to sync carers from an HR system, recruitment tool, or data warehouse into OneTouch. Use Create to onboard new carers and Update to keep existing carer details in step with your source system. To read carers and other OneTouch objects into a pipeline, use the OneTouch Health source instead.Connection
Select an existing OneTouch Health connection or create a new one. The destination uses the same connection as the source. See OneTouch Health connection setup. Connect with Username & password for any job that may run longer than about 15 minutes. OneTouch tokens expire after roughly 15 to 20 minutes. With a username and password, Integrate.io logs in again when the token expires. With an API token, the job fails once the token expires. A package can read from and write to OneTouch on the same connection. OneTouch revokes a user’s previous token on every new login. To avoid revoking each other’s token, the source and destination share the most recent token. Don’t share the OneTouch user with other tools or environments. See the dedicated user warning.Master key or location-restricted key
The kind of OneTouch key behind the user decides which location fields a record needs:Destination properties
- OneTouch object - the object to write. Carers is the only object. Changing the object clears the field mapping.
-
Operation - what the component does with each record:
- Create (default) - posts each record as a new carer. OneTouch rejects a record whose
external_idalready belongs to a carer. - Update (matched on external_id) - updates the carer with the matching
external_id. Empty values are not sent. With a master key, Update also needslocationorbranch.
- Create (default) - posts each record as a new carer. OneTouch rejects a record whose
Advanced options
- Requests per second - throttle applied to the OneTouch API. Default is
8, which is OneTouch’s documented limit. Accepts values from0.1to8. Each record is one request. Lower this value if other integrations use the same OneTouch login. - Maximum errors - the job fails once the number of failed records exceeds this value. Default is
0(fail on the first failed record). Set to-1to allow unlimited failures. - Output failed records (CSV) - writes rejected records to a CSV. Select an Errors output connection and enter an Errors output path.
- Output written records (CSV) - writes records that OneTouch accepted to a CSV. Select a Written records output connection and enter a Written records output path.
Field mapping
Map input fields to OneTouch carer fields. The mapping step starts with rows for the three required fields, without an input field selected. Click Auto-fill to map every input field whose name matches a carer field. You can’t complete the step until every required field has an input field selected. Required fields (both operations):
Optional fields:
Integrate.io checks each record before sending it. A record fails without a request to OneTouch when a required field is empty, a date isn’t in
yyyy-mm-dd format, unique_email isn’t a boolean value, or unique_email is true without a primary_email. Failed records count toward Maximum errors.
When you save or validate the package, Integrate.io also checks the mapping. Validation fails when the mapping:
- Leaves out
external_id,firstname, orlastname. - Includes a field that isn’t in the carer field list above.
- Maps the same carer field more than once.
- Maps both
ppsandni_number.
IDs and names
transport_type, recruitment_source, position, location, branch, area, and status take either an ID or a name. OneTouch tells them apart by the type of value it receives, and the component sends each value with the type of its input field:
An ID held in a text field therefore fails, typically with “Location not found”. The OneTouch Health source can return IDs as text, so cast them to a number before the destination, for example in a Select transformation:
status takes a status configured in your OneTouch account, by its name or ID (read the CarerStatuses object to list them). It does not take a status type: “Archived” fails with “No mathching status found” (OneTouch’s spelling) unless a status is named exactly that. To archive a carer, run Update with status set to a status whose type is Archived.
Success and error tracking
Both CSV outputs are optional and configured independently. Supported storage connections are Amazon S3, Google Cloud Storage, Azure Blob Storage, SFTP, and FTPS.- The failed records CSV has an
Errorcolumn with OneTouch’s error message, aRequest JSONcolumn with the payload that was sent, and one column per mapped field. - The written records CSV has a
OneTouch Idcolumn with the carer’s OneTouch ID, followed by one column per mapped field.
Retries
Integrate.io retries a request when OneTouch returns HTTP 429 or a 5xx error, or doesn’t answer in time, and honors theRetry-After header up to 60 seconds. If a 429 or 5xx persists through every retry, the record counts as failed. If three records in a row fail this way, the job stops, because OneTouch is likely unavailable. If OneTouch doesn’t answer at all after every retry, the job stops straight away.
Other errors, such as a duplicate external_id, an unknown position, or a missing location or branch with a master key, fail only that record. The failed records CSV shows OneTouch’s message with its per-field details. An expired token stops the job on an API token connection; with Username & password, Integrate.io logs in again and continues.
A retried Create never creates a second carer. OneTouch rejects a duplicate external_id. If the first attempt may have succeeded, Integrate.io looks up the carer by external_id and reports the record as written when OneTouch holds the values that were sent.
Integrate.io doesn’t retry failed job tasks for this destination. A retried task would resend carers the failed attempt already wrote, and OneTouch would reject them as duplicates. A task the cluster kills, for example when its node is lost, still runs again and resends its records. If a job fails, check the failed records CSV before you run it again.
Best practices
- Run jobs on a recently created cluster. Clusters get the OneTouch destination connector when they are created. Create a new cluster before you run your first OneTouch destination job.
- Test on a small sample first. Each record that OneTouch accepts creates or changes a real carer.
Example: syncing new carers from a warehouse query
A pipeline that reads carers hired in the last day and creates them in OneTouch:location and area are needed with a master key; they come from integer columns, so they are sent as IDs. position is sent as a name and must match an existing OneTouch position exactly. Turn on Output failed records (CSV) with an S3 connection so you can review rejected records after the run. Use a second component with Update in a separate package to push changes to existing carers.
FAQ
Q: Why did a record fail with “The location field is required when branch is not present”? The connection uses a master key, and OneTouch needslocation or branch on every create and every update. Map one of them on the component.
Q: Why did a record fail with “Location not found”?
The location value reached OneTouch as text, so OneTouch looked for a location with that name. Cast the ID to a number, for example (int)location_id. See IDs and names.
Q: Why did a record fail with “No mathching status found”?
status takes a status configured in your account, not a status type such as “Archived”. Read the CarerStatuses object with the OneTouch Health source to list the valid names and IDs.