> For the complete documentation index, see [llms.txt](https://developers.share.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.share.inc/splynx/installations-and-tasks.md).

# Installations and Splynx tasks

When Share schedules a physical installation for a new subscriber, it creates a corresponding **scheduling task** on your partner's Splynx tenant. Your field team picks it up from the Splynx mobile app, dispatches a technician, and marks it done — exactly the same workflow they already use for any other Splynx task. This page walks through that lifecycle from both sides.

If your operation uses its own field-dispatch tooling instead of Splynx, tell your account manager — the outbound task creation is opt-in per partner.

## In three steps

1. **An installation is scheduled.** Either you create it through the Share API or admin platform, or your CSR creates a new internet-service in Splynx with `installation_required = true`.
2. **A task appears in Splynx.** Share creates the task in the *Share Installations* project on your Splynx instance, in the **To Do** column. Your dispatcher picks it up from there.
3. **The technician marks it done.** The Splynx task moves to the **Done** column, Splynx notifies Share, and Share advances the subscriber's onboarding (RADIUS provisioning or first-cycle activation, depending on payment state).

Everything below is detail on how each step works.

## The "Share Installations" project

When your Splynx is connected ([Connect your Splynx](/splynx/connect-your-splynx.md)), Share provisions a **Scheduling project** in Splynx called *Share Installations* on your instance. The project has the standard Splynx workflow columns (To Do → In Progress → Done, plus Cancelled). This project is created once and reused for every installation afterwards.

You do not need to create the project manually. If you delete or rename it, Share recreates it on the next installation.

## When a task is created

A Splynx scheduling task is created when an installation is **scheduled** on the Share side. That can happen two ways:

* **From the Share API or admin platform** — create an installation with the subscriber, the type (`INITIAL` / `REPLACEMENT` / `RELOCATION`), and an optional `scheduledDate`. The exact request shape is in the [API Reference](/api-reference/api-reference.md) under **Installations → Create installation**.
* **From Splynx** — your CSR creates a new internet-service with `installation_required = true` (a custom field on the service). Splynx sends Share a `service.create` webhook and Share treats it as a new installation.

Either way, Share queues an outbound write to Splynx that creates the task in the *Share Installations* project, in the **To Do** column.

## What lands on the Splynx task

| Splynx task field | What Share puts there                                                                                                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Title             | Installation type and subscriber name (e.g. *Initial install — Jane Doe*)                                                                                  |
| Description       | Subscriber address, contact phone, the linked Share installation id, and any notes carried from the create call                                            |
| Column            | **To Do** at creation time                                                                                                                                 |
| Scheduled date    | The `scheduledDate` from the Share installation if it was provided. If not, the task is left undated and your dispatcher schedules it from the mobile app. |
| Assignee          | Unassigned. Your dispatcher assigns a technician from the mobile app.                                                                                      |
| Project           | *Share Installations* on your Splynx instance                                                                                                              |

In addition to the task itself, Share sets two custom fields on the subscriber's Splynx internet-service so your field team can see expectations at a glance:

* `installation_required` — set to `false` once the task exists, then back to `true` only if the task is cancelled and a new one needs to be created.
* `installation_paid` — set to `true` if the installation is free or the installation fee has already been collected on the Share side; `false` otherwise. Field teams typically refuse to dispatch when this is `false`.

## The lifecycle, end to end

```mermaid
sequenceDiagram
  participant Share
  participant Splynx
  participant Technician

  Share->>Splynx: Create task in "Share Installations" (To Do)
  Splynx-->>Share: task id
  Technician->>Splynx: Assign self, schedule, drive to site
  Technician->>Splynx: Move task to Done
  Splynx-->>Share: scheduling_task.edit webhook
  Note over Share: Installation transitions to AWAITING_INSTALLATION or AWAITING_CYCLE_PAYMENT
```

### Moving to Done

When a technician completes the install and moves the Splynx task to the **Done** column, Splynx fires a `scheduling_task.edit` webhook. Share recognises the partner's "done" workflow status (cached per partner the first time the project is provisioned) and:

* Marks the Share installation as completed.
* Triggers the next step in the subscriber's onboarding — usually RADIUS provisioning, or first-cycle activation if the cycle was waiting on the install.
* Emits a webhook on Share's side (`installation.completed`) if you have webhook delivery configured.

### Moving to Cancelled

If the install cannot happen (customer no-show, address change, etc.) and the task is moved to the **Cancelled** column, Splynx fires the same `scheduling_task.edit` webhook. Share treats this as a cancellation:

* The Share installation is marked `CANCELLED`.
* Any linked one-time installation charge that has not yet been collected is cancelled too.
* `installation_required` is flipped back to `true` on the service so your CSR or the next workflow can re-trigger.

### Reschedule mid-flight

If your dispatcher edits the task's scheduled date in Splynx, Share **does not flip back** anything on its side — Splynx is the source of truth for the schedule. The Share installation's `scheduledDate` may go briefly stale; reconciliation refreshes it within an hour.

## What you can verify yourself

* **Splynx Scheduling → Projects → Share Installations.** Every task Share creates appears here, with the Share installation id in the description so you can join back if you need to.
* **Splynx audit log filtered by Share's API key.** Shows the task creation, the service custom-field updates, and the project provisioning.
* **Share's outbound webhooks.** `installation.scheduled`, `installation.completed`, and `installation.cancelled` mirror the same lifecycle on Share's side. The two streams should agree.

## Common gotchas

* **The task appeared in Splynx with no scheduled date.** Either the Share installation was created without one, or the inbound webhook from your CSR's service-create did not carry one. Edit the task to set a date — Share will not overwrite it.
* **Technician moved the task to Done and nothing happened on Share's side.** Most often this means the partner's "done" status id was not what Share cached. Ask your account manager to refresh the workflow-status mapping for your partner.
* **You see an installation stuck in "AWAITING\_CYCLE\_PAYMENT" after the task completed.** That is expected when the first-cycle payment has not landed yet. Once the payment completes the subscription activates automatically.
* **Two tasks for the same install.** Usually caused by deleting the *Share Installations* project mid-flight. The project gets recreated and the next install attempt creates a fresh task. Move the old one to Cancelled to keep your dispatcher's queue tidy.